apiDoc 可以通过文本生成体验良好的 API 文档页面,这些文本可以以注释的形式放在代码里,apiDoc 读取源码注释,就可以生成页面了,当然也可以与代码分开,写一些全是注释的文档,作为 apiDoc 生成文档页面的「源文件」。

整理一下 apiDoc 「源文件」内容写法的“最小必要知识”。其余内容,查文档。

基础

用一个「文档块」来描述一个 API,这个「文档块」也是实现 API 的代码的注释。

一个文档块以 /** 开始,*/ 结束。

一个例子:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/**
 * @api {get} /user/:id Request User information
 * @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"
 *     }
 */

这个例子描述了一个获取用户信息的 GET 方法。

  • @api {get} /user/:id Request User information 这一行内容是必需的,表示了这个 API 的 HTTP 方法(method),路径(path,这个例子中的路径带了一个参数),Request User information 是这个 API 的 title
  • @apiName 必须是唯一的,最好总是加上这个字段。
  • @apiGroup 最好也总是加上,用于把有关联的 API 放到一个组。
  • 其他字段比如 @apiError, @apiSuccess 等是可选的。

继承

可以通过「继承」复用「文档块」

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
/**
 * @apiDefine UserNotFoundError
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

/**
 * @api {get} /user/:id Request User information
 * @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"
 *     }
 *
 * @apiUse UserNotFoundError
 */

/**
 * @api {put} /user/ Modify User information
 * @apiName PutUser
 * @apiGroup User
 *
 * @apiParam {Number} id          Users unique ID.
 * @apiParam {String} [firstname] Firstname of the User.
 * @apiParam {String} [lastname]  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *
 * @apiUse UserNotFoundError
 */

上面的例子用 @apiDefine 定义了一个可复用的文档块 UserNotFoundError,然后在 GetUserPutUser 两个 API 文档块中通过 @apiUse UserNotFoundError 复用文档块。

注意,只能继承一层。


下面把 apiParams 专门挑出来。

apiParams

apiParams 用来描述 API 的参数,它并没有提供什么手段去区分是路由参数、URL 查询参数还是在 HTTP BODY 里的参数。

1
@apiParam [(group)] [{type}] [field=defaultValue] [description]`

除了 field,其余内容都是可选的。如果写 @apiParam 时,给 field 加了一对中括号,这样是指定了这个 field 是个可选参数。

group 是给参数分组,type 指定参数的数据类型。

例子:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
/**
 * @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.
 */

@apiParamExample 用来描述参数样例

1
2
@apiParamExample [{type}] [title]
                   example

typetitle 都是可选的。

例子:

1
2
3
4
5
6
7
/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 4711
 *     }
 */

一个完整的例子: