使用apidoc生成api文档

为什么要用apidoc

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

安装和配置apidoc

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

{                                                                                                                                          
    "name":"xxxxx API",                                                                                                               
    "version":"1.0.0",                                                                                                 
    "title":"xxxxx API Document",
    "description":"xxxx API开发者指南"
    }  

如何使用

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正常示例

生成文档

执行命令apidoc -i （目标路径或文件） -o （生成路径）