为什么要用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 (生成路径)