Nodejs 使用 apidoc生成Restfull API 文档

工具名称：apiDoc
Git地址：https://github.com/apidoc/apidoc
项目地址：http://apidocjs.com/

1. 安装apiDoc

npm install apidoc -g

参数说明：
-f 文件过滤
使用正则表达式，表示哪些文件需要本转换，不设置的情况下，默认为.cs .dart .erl .go .java .js .php .py .rb .ts 后缀的文件。

-i 代码文件夹

-o 输出Api文档的路径

-t 使用模板文件的路径，可以自定义输出的模板

2. 配置 apidoc.json

无package.json文件时，需要在代码文件夹的根目录下，创建apidoc.json文件。

{
  "name": "Apidoc Example",
  "version": "1.0.0",
  "description": "Apidoc Example descrption",
  "title": "Custom apiDoc browser title",
  "url" : "http://localhost:8000/api/v1",
  "sampleUrl": "http://localhost:8000/api/v1",
  "template": {
    "withCompare": true,
    "withGenerator": true
  }
}

3. 添加接口注释

/**
     *
     * @api {post get} /{model}/query  查询数据
     * @apiName query
     * @apiGroup 业务单元基础
     * @apiVersion 1.0.0
     * @apiDescription 接口详细描述
     *
     * @apiParam {Object} body 请求参数JSON对象
     *
     * @apiSuccess {String} status 结果码
     * @apiSuccess {String} message 消息说明
     * @apiSuccessExample Success-Response:
     *  HTTP/1.1 200 OK
     *  {
     *    code:1,
     *    message:'success',
     *    data:{total:100, result:[]}
     *   }
     *  @apiErrorExample {json} Error-Response:
     *  HTTP/1.1 200
     *  {
     *     code:0,
     *     message:'user not found',
     *   }
     *   @apiPermission Auth
     */
    query: function (req, res) {}

4. 执行生成命令

apidoc -i ./server/routes/ -o ./doc/apidoc/

---

注意事项

1. @apiGroup 中文问题处理

C:\Users\Administrator\AppData\Roaming\npm\node_modules\apidoc\node_modules\apidoc-core\lib\workers\api_group.js
注释掉
//group = group.replace(/[^\w]/g, ‘_’);

2. @apiName 必须是英文。

接口打开路径会根据 @apiGroup + @apiName