阅读 333

接口文档利器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文件访问,以支持线上访问接口文档。


关注下面的标签,发现更多相似文章
评论