0%

使用 apiDoc 自动生成 API 文档

前段时间尝试写 API 服务器,为了方便管理数量可能越来越多的接口(未雨绸缪),必须考虑创建文档的方案。我选择了 apiDoc 作为第一款文档生成工具。apiDoc 是一个通过代码中的注释生成 API 文档的工具,它简单易用,并且支持多种常用编程语言。

安装

使用 NPM 全局安装 apiDoc :

1
npm install apidoc -g

配置

在项目根目录下新建 apidoc.json 配置文件。注意:json 文件不能包含注释,下面的注释只是为了方便解释选项含义。

1
{
2
  "name": "example",  // 项目名称
3
  "version": "0.1.0",  // 项目版本
4
  "description": "apiDoc basic example",  // 项目描述
5
  "title": "Custom apiDoc browser title",  // 文档标题
6
  "url" : "https://api.github.com/v1",  // 链接前缀
7
  "template": { // 模板配置
8
    "forceLanguage": "zh_cn"
9
  },
10
  "order": [ // 排列顺序
11
    "Auth",
12
    "Users",
13
    "Goods"
14
  ]
15
}

其中,title 是文档的主标题,留空使用 name 渲染。

url 是链接前缀,文档中的 API 链接都会带上这个前缀。这样做的好处是不必总是写完整的 API 链接,即使换域名也只需修改一处。

模板相关配置 template 并不是必要的,这里我指定了渲染的语言为简体中文。

order 同样是一个可选的配置项,用于设置分组的显示顺序。

撰写

使用注释撰写 API 信息。一个简单的接口描述只需声明 @api@apiName@apiGroup 三个参数。

1
/**
2
 * @api {get} /user/:id 获取用户
3
 * @apiName GetUser
4
 * @apiGroup User
5
 */

@api 必须,声明请求类型、路径、标题(显示在文档中)。@apiName 声明接口显示在文档中的容器 id ,官方建议必填,实际上不声明也会自动生成。@apiGroup 必填,声明接口分组。

在此基础上进一步声明参数和响应。

1
/**
2
 * ...
3
 *
4
 * @apiParam {Number} id 用户 id
5
 *
6
 * @apiSuccess (200) {String} name  用户名
7
 * @apiSuccess (200) {String} email 用户的邮箱地址
8
 *
9
 * @apiSuccessExample {json} 请求成功:
10
 *     HTTP/1.1 200 OK
11
 *     {
12
 *       "name": "张三",
13
 *       "email": "foo@example.com"
14
 *     }
15
 *
16
 * @apiError UserNotFound 未找到指定的用户
17
 *
18
 * @apiErrorExample 请求失败:
19
 *     HTTP/1.1 404 Not Found
20
 *     {
21
 *       "error": "UserNotFound"
22
 *     }
23
 */

@apiParam 选填,声明一个参数的类型、参数名、描述。

@apiSuccess 选填,声明请求成功后的响应分组、字段类型、字段(或成功代码)、字段描述。@apiSuccessExample 选填,声明请求成功后响应内容的格式、标题和示例。声明错误的 @apiError@apiSuccessExample 与之类似。

Tips: 分组名称不可以直接使用中文。应该用 @apiDefine 声明一个值为中文组名的变量,然后在声明 API 分组时使用它。

1
/**
2
 * @apiDefine Auth 认证
3
 */
4
5
/**
6
 * @api {post} /auth
7
 * @apiGroup Auth
8
 */

生成

1
apidoc -i ./ -o apidoc

-i--input 参数表示输入目录。-o--output 参数表示输出目录。-i ./ -o apidoc 的意思是:扫描当前目录下的文件,然后在当前目录下的 apidoc 文件夹中生成文档。

另外,可以使用 -f--file-filters 参数过滤文件类型。

1
apidoc -f ".*\\.js$" -f ".*\\.ts$"

相关环境:Windows 7 x64 / Node.js 6.10.1 / npm 3.10.10 / apiDoc 0.17.6