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

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

安装

# 全局安装
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文件访问，以支持线上访问接口文档。