接口文档利器apidoc

顾名思义，apidoc是用于接口文档，并且是根据代码注释自动生成的，也能在线调用，类比swagger。  

apidoc官网。本文大部份内容摘自：ApiDoc 后端接口注释文档的使用

安装

# 全局安装
yarn global add apidoc 
# 查看是否安装成功
apidoc -h 复制代码

命令说明

• -f：--file-filters 过滤器，指定应该解析的文件类型、后缀 （能够使用多个-f）。默认.cs .dart .erl .go .java .js .php .py .rb .ts。示例（仅解析.js和.ts文件）：apidoc -f ".*\.js" -f ".*\\.ts"
• -e：--exclude-filters 过滤器用于选择不该该解析的文件
• -i： --input 指定输入的源目录名，项目文件的位置，默认为 ./ 例：apidoc -i myapp/ 
• -o： --output 指定输出的目录文件名，放置生成文档的位置，默认为 ./doc/，例：apidoc -o apidoc/ 
• -t： --template 指定要用的外部模板的路径，能够建立和使用本身的模板，默认使用全局的 node_modules/apidoc/template/ ，例：apidoc -t mytemplate/ 
• -c： --config 指定配置文件的路径 apidoc.json ./ 
• -h： --help 显示详细的帮助说明 
• --debug： --debug 显示调试的信息，默认为 false

使用说明

在项目文件夹下新建 apidoc.json ，或者在 package.json 下建立 apidoc 节点。示例：

• apidoc.json（我的推荐这种方式）

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}复制代码

• package.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": {
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1"
  }
}复制代码

详细配置说明：

• name：项目名称，若不存在该字段，则会尝试取 package.json 里面的name值 
• version：项目版本号，不存在则读取 package.json 里面对于的值 
• description：项目描述 ，不存在同上 
• title：浏览器标题文本 
• url：api路径的前缀，适合同一域下的接口，例：https://api.github.com/v1 
• sampleUrl：测试样例的url, 具体请参考 @apiSampleRequest 
• header：添加自定义的顶部描述 {title: '', filename: ''} 
• title：顶部的标题 
• filename：顶部具体的展示内容 
• footer：添加自定义的尾部描述 {title: '', filename: ''} 
• title：尾部的标题 
• filename：尾部具体的展示内容 
• order：用于定义输出的api-names/group-name列表排序。最后自动显示未定义的名称。"order": ["Error","Define","PostTitleAndError","PostError"]
  

API说明

• 经常使用API：api、apiName、apiGroup、apiVersion、apiDescription、apiParam、apiSuccess、apiSuccessExample、apiDefine、apiError、apiIgnore，示例：

/**
 * @api {get} /user/:id Request User information
 * @apiVersion 0.1.0
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */复制代码

文档块以 /** 和 */ 结尾，其中@api为必须字段，格式同例子：@api + {请求类型} + 接口路径 + 接口描述，在生成的时候没有@api 的文档块会被忽略。@apiName 和 @apiGroup,在版本迭代时应保持一致，其余字段为可选。

• @api (必须字段，没有会被忽略)

@api {method} path [title]复制代码

示例：@api {get} /user/:id Users unique ID.

• @apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]复制代码

说明：1. 带中括号[]的Fieldname将Variable定义为可选，[]内部是须要的格式。2. =defaultValue 参数默认值。3.入参能够用[(group)]进行分组。

示例：（2个）

/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
*/

/**
* @api {post} /user/
* @apiParam {String} [firstname]  Optional Firstname of the User.
* @apiParam {String} lastname     Mandatory Lastname.
* @apiParam {String} country="DE" Mandatory with default value "DE".
* @apiParam {Number} [age=18]     Optional Age with default 18.
*
* @apiParam (Login) {String} pass Only logged in users can post this.
*                                 In generated documentation a separate
*                                 "Login" Block will be generated.
*/复制代码

• @apiSuccess

@apiSuccess [(group)] [{type}] field [description]复制代码

示例：（3个）

/** * @api {get} /user/:id * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */

/** * @api {get} /user/:id * @apiSuccess (200) {String} firstname Firstname of the User. * @apiSuccess (200) {String} lastname Lastname of the User. */

/** * @api {get} /user/:id * @apiSuccess {Boolean} active Specify if the account is active. * @apiSuccess {Object} profile User profile information. * @apiSuccess {Number} profile.age Users age. * @apiSuccess {String} profile.image Avatar-Image. */复制代码

踩坑记录

• 配置好、添加Demo注释以后执行 apidoc 提示大量下面的错误。缘由是未屏蔽 node_modules ，须要添加-e，如apidoc -e node_modules，或者添加-i，如 apidoc -i src/。

{"message":"parser plugin 'return' not found in block: 13","level":"warn"}
{"message":"parser plugin 'param' not found in block: 14","level":"warn"}
{"message":"parser plugin 'return' not found in block: 14","level":"warn"}复制代码

使用经验

• 在node项目里配置static文件访问，以支持线上访问接口文档。