为什么要用apidoc

• apidoc根据其自定义注释语法自动生成api文档，我们只需要把代码中的注释按照其语法来写就能生成需要的文档，不需要手动写markdown。
• apidoc生成的文档相比markdown，漂亮直观又实用。
• 如果API需要修改或者更新，直接修改代码的注释中即可。apidoc核心思路，文档与代码合一，修改代码就是修改文档，方便又实用。
• 可以配合grunt使用，使自动化生成文档更加智能，支持多种语言。

0x01 安装和配置apidoc

• 首先要确认你的系统安装了nodejs，然后执行npm install -g apidoc即可。
• 配置apidoc，在你的项目下创建apidoc.json文件，apidoc.json说明

{
    "name": "测试APIs",   
    "version": "1.0.0",                
    "description": "接口测试",
    "title": "test APIs",
    "url" : "http://localhost:9220/sapi/v1/production_plan",
    "sampleUrl" : "http://localhost:9220/sapi/v1/production_plan"
}

0x02 如何使用

apidoc是根据其自定义注释语法来生成文档的，语法可参考apidoc Params
下面是作者的一些注释代码，可以参考这个把注释写到你的代码相应的位置：

/**
 * @api {get} /test 接口测试
 * @apiDescription 根据ID（id）获取列表信息
 * @apiGroup test APIs
 *
 * @apiParam {Number} id 任务ID
 * @apiParam {Number} [page] 页数
 * @apiParam {Number} [perpage] 每页的条数
 *
 * @apiParamExample {string} 请求参数格式:
 *    ?id=123&page=1&perpage=20
 *
 * @apiVersion 1.0.0
 * @apiErrorExample {json} 错误返回值:
 *     {
 *        "code": 10003,
 *        "msg": "ParametersError [Method]:get_tests参数错误!",
 *        "error": {
 *            "id": "",
 *            "page": "",
 *            "perpage": ""
 *        },
 *       "status": "fail"
 *     }
 * @apiSuccessExample {json} 正确返回值:
 *     {
 *   "code": 0,
 *   "msg": "OK ",
 *   "data": [
 *       {
 *           "id": "622051004185471233",
 *           "testCode": "000050",
 *       }
 *   ],
 *   "status": "ok",
 *   "count": "14"
 *   }
 */

• @api 定义API的请求方法、路径和名字
• @apiDescription 定义API的描述
• @apiGroup 定义API的分组
• @apiParam 定义API的参数
• @apiParamExample 参数请求的事例
• @apiVersion 版本
• @apiErrorExample API错误示例
• @apiSuccessExample API正常示例

0x03 生成文档

执行命令apidoc -i src/ -o apidoc/

• -i src/是把src文件夹下带有apidoc语法注释的代码全部生成文档
• -o apidoc/是文档的生成目录
  一切大功告成，打开apidoc文件夹下的index.html文件

文档界面

点我进入apidoc官网

简书作者 小菜荔枝 转载请联系作者获得授权