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

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

基础

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

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

一个例子：

/**
 * @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 等是可选的。

继承

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

/**
 * @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，然后在 GetUser 和 PutUser 两个 API 文档块中通过 @apiUse UserNotFoundError 复用文档块。

注意，只能继承一层。

下面把 apiParams 专门挑出来。

apiParams

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

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

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

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

例子：

/**
 * @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 用来描述参数样例

@apiParamExample [{type}] [title]
                   example

type 和 title 都是可选的。

例子:

/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 4711
 *     }
 */

一个完整的例子：