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
* }
*/
一个完整的例子：