Node.js ApiDoc 工具手册中文译本
以下内容，均为官方文档的中文译稿，如在学习过程中发现有误，请不吝赐教，指正修改。
1. DEMO
访问站点：http://apidocjs.com/#demo
查看演示效果。
2. 入门
2.1 前言
文档中所有的示例都使用了Javadoc风格（也可使用C#、Go、Dart、Java、JavaScript、PHP、TypeScript以及其他支持Javadoc的语言）：
/**
* This is a comment.
*/对于其他语言使用其他特定的多行注释代码：
- CoffeeScript
###
This is a comment.
###- Elixir
@apidoc """
This is a comment.
"""- Erlang(%在注释中是可选的)
%{
% This is a comment.
%}- Perl(Doxygen)
#**
# This is a comment.
#*- Python
"""
This is a comment.
"""- Ruby
=begin
This is a comment.
=end- Lua
--[[
This is a comment.
--]]2.2 安装
这里很简单就是利用npm进行安装，详细安装过程在上面讲过：
npm install apidoc -g2.3 运行
apidoc -i myapp/ -o apidoc/ -t mytemplate/将目录myapp里的文件，使用目录mytemplate目录下的模板文件来生成的apidoc文档最后存储在目录apidoc下。
如果不指定参数，apiDoc会根据当前目录下全部的.cs、.dart、.erl、.go、.java、.js、.php、.py、.rb、.ts文件来生成文档到当前目录的doc目录下。
2.4 命令行
通过命令行参数查看帮助信息：
apidoc -h重要参数讲解：
2.5 GRUNT模式
支持单独的grunt模式，参见：github.com/apidoc/grunt-apidoc
或者通过npm来安装：
npm install grunt-apidoc --save-devgrunt是一套前端自动化工具，一个基于nodejs的命令行工具，一般用于：压缩文件、合并文件、简单语法检查。
关于grunt的可访问官方网站获取详细信息：https://gruntjs.com/
这里暂不做深入讨论。
2.6 模板
apiDoc包含一个默认的模板使用handlebars、Bootstrap、RequireJS和jQuery用于输出生成的api_data.js和api_project.js作为一个html页面。
默认情况下生成的apiDoc文档使用复杂的模板，支持：
versioning：查看你的API接口不同版本
compare：对比你的API接口在两个版本之间的变化
查看示例，这里我在官方演示demo里随便对比了一个版本差异效果如图：
创建属于自己的模板
当然你也可以创建一个你自己的模板来生成apiDoc文档的api_data.js、api_project.js或者仅json文件api_data.json、api_project.json。
查看模板的源代码：https://github.com/apidoc/apidoc/tree/master/template
2.7 扩展
apiDoc可以通过你自己的参数进行扩展（如果有一些是你不需要的）。以在apidoc/apidoc-core项目上的lib/parsers/、lib/workers和lib/filters/目录为例，parser分离参数数据，worker用所有找到的数据处理附件函数，filter减少数据需要的东西。
示例：
apidoc --parse-filters myFilter=pathToMyFilter/myFilter.js这要比请求整个项目创建来生成apiDoc要好。
2.8 配置文件（apidoc.json）
apidoc.json是可选的在你的项目根目录下，包含你项目的一些基本信息，比如标题、摘要、版本等，配置项像header/footer或者模板特定选项。
apidoc.json示例：
{
"name": "apidoc-example",
"version": "0.3.0",
"description": "apiDoc example project",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1",
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
},
"order": [
"GetUser",
"PostUser"
],
"template": {
"withCompare": true,
"withGenerator": true
}
}如果你使用了package.json（eg：在node.js项目里），所有的apidos.json配置可以同样由package.json来完成，只需要把它们添加到"apidoc":{}参数下即可。
package.json示例：
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"apidoc": {
"title": "Custom apiDoc browser title",
"url": "https://api.github.com/v1"
}
}apidoc.json的基本配置信息：
| 参数名 | 描述 |
|---|---|
| name | 项目名称，如果在apidoc.json中不存在此字段，apiDoc将会通过package.json中的值来命名 |
| version | 项目版本，如果在apidoc.json中不存在此字段，apiDoc将会通过package.json中的值来命名 |
| description | 项目描述，如果在apidoc.json中不存在此字段，apiDoc将会通过package.json中的值来命名 |
| title | 浏览器标题 |
| url | api接口路径前缀（端点），eg：https://api.github.com/v1 |
| sampleUrl | 如果设置了，那么一个用于测试api方法（发送请求）将会可用。具体参见@apiSampleRequest获取更多细节 |
| header | |
|
对于包含header.md文件的导航文本（参见：Header/Footer） |
|
对于包含header.md文件的文件名（markdown文件） |
| footer | |
|
对于包含footer.md文件的导航文本 |
|
对于包含footer.md文件的文件名（markdown文件） |
| order | 输出的api名称/组名称顺序列表。未定义的名称将自动显示在最后 |
"order":["Error", "Define", "PostTitleAndError", "PostError"] |
模板中的特殊配置
接下来的这些配置都是apiDoc默认模板里的特殊配置。
| 参数名 | 类型 | 描述 |
|---|---|---|
| template | ||
|
String | 禁用浏览器的语言自动检测并且设置特定的区域设置，例如：de、en，查看可用区域：here |
|
Boolean | 允许与旧版本的API进行比较，默认值为：true |
|
Boolean | 在页脚输出生成器信息，默认值为：true |
|
Object | 设置Ajax请求的默认值 |
2.9 页眉/页脚
在你项目的apidoc.json配置文件中你可以增加页眉和页脚。
标题将会在导航中可见，文件名应该是markdown格式。
示例：
{
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
}
}3. 示例
一个小的演示介绍示例：speakerdeck.com
3.1 基本
在基本示例中我们有一个小的项目文件和一个apidoc.json配置文件。
演示效果就不截图了，大家访问这个地址查看即可：http://apidocjs.com/example_basic/
apidoc.json
完整的代码：
{
"name": "example-basic",
"version": "0.1.0",
"description": "apiDoc basic example",
"template": {
"withCompare": false
}
}通过apidoc.jsonapiDoc获取到你项目的名称、版本、描述信息，这个文件是可选的，它取决于你的模板里是否要求有这些数据。
example.js
完整的代码：
/*
* Basic Example
*
* This is a basic example for apiDoc.
* Documentation blocks without @api (like this block) will be ignored.
*/
/**
* @api {get} /user/:id Get 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"
* }
*/这个文档块以/**开始，以*/结尾。
示例描述了一个通过用户id请求用户信息的GET请求方法。
@api {get} /user/:id Request User information是强制的，不带@api的apiDoc将会忽略文档块。
@apiName必须是一个独特的名字并且要一直使用。
格式：method + path （eg：Get + User）
@apiGroup应该一直使用，用于将相关的APIs组合在一起。
其余的字段都是可选的，查看它们的描述信息：apiDoc-Params
3.2 继承
使用继承，可以定义文档的可重用代码段。
演示效果就不截图了，大家访问这个地址查看即可：http://apidocjs.com/example_inherit/
apidoc.json
完整的代码：
{
"name": "example-inherit",
"version": "0.1.0",
"description": "apiDoc inherit example",
"template": {
"withCompare": false
}
}example.js
完整的代码：
/*
* Inherit Example
*
* This is an inherit example for apiDoc.
* Define parts of your documentation that shall be used many times.
*
* In this case a block named "UserNotFoundError" is defined with "@apiDefine".
* That block could be used many times with "@apiUse UserNotFoundError".
*
* Documentation blocks without @api (like this block) will be ignored.
*/
/**
* @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 Get 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的代码块。这段代码块可以通过@apiUse UserNotFoundError引用多次。
在生成的输出文档中，GET和PUT两个方法都拥有完整的UserNotFoundError文档。
使用apiDefine来定义一个继承块。
使用apiUse、apiGroup和apiPermission来引用继承块。但是参数不能继承，只有标题、描述（结合api的版本）。
继承只能工作在1级父子关系下，过多层级会使得代码不可读，并且非常复杂。
3.3 版本控制
apiDoc提供的一个非常有用的功能是维护API所有先前版本和最新版本的文档。这使得与前任版本做对比的方法成为可能。前端开发人员可以很清楚的看到改变了什么，然后更新他们的代码。
演示效果就不截图了，大家访问这个地址查看即可：http://apidocjs.com/example_versioning/
在这个示例中，点击顶部右侧的选择框（主版本）选择Compare all with predecessor：
主要变化内容都用绿色标记出来了
每个方法都展示了与之前版本对比实际不同的部分
绿色标记的内容都是新增的（在这个示例中标题部分有改变并且
registered是新增的）
你可以将主版本（右上角）更改为以前的版本，并将旧的方法与它们的之前版本进行比较。
- apidoc.json
{
"name": "example-versioning",
"version": "0.2.0",
"description": "apiDoc versiong example"
}为了避免API文档随着时间的推移而发生代码膨胀，它建议使用一个单独的历史文件名为_apidoc.js，在你准备改变你的文档块之前，拷贝旧的文档到这个文件，apiDoc将会自动包含历史信息:
_apidoc.js
/**
* @api {get} /user/:id Get 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"
* }
*/总结上面那段话的意思就是：如何处理旧文档里的历史内容呢，就是加入到指定文件名下_apidoc.js下即可。
example.js（你的当前项目文件）
/**
* @api {get} /user/:id Get User information and Date of Registration.
* @apiVersion 0.2.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.
* @apiSuccess {Date} registered Date of Registration.
*
* @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"
* }
*/重要的就是在每个文档块中使用@apiVersion来设置版本。
版本字段会作用在每个块，也包括继承块。你不必在继承块中改变版本，语法分析器将会自动检查最近的版本。
3.4 完整示例
一个复杂的示例包括了继承inherit、版本文件versioning和历史文件_apidoc.js，解释在代码内和生成文档中。
示例的输出效果，参见：http://apidocjs.com/example/
包含文件：
- _apidoc.js
// ------------------------------------------------------------------------------------------
// General apiDoc documentation blocks and old history blocks.
// ------------------------------------------------------------------------------------------
// ------------------------------------------------------------------------------------------
// Current Success.
// ------------------------------------------------------------------------------------------
// ------------------------------------------------------------------------------------------
// Current Errors.
// ------------------------------------------------------------------------------------------
/**
* @apiDefine CreateUserError
* @apiVersion 0.2.0
*
* @apiError NoAccessRight Only authenticated Admins can access the data.
* @apiError UserNameTooShort Minimum of 5 characters required.
*
* @apiErrorExample Response (example):
* HTTP/1.1 400 Bad Request
* {
* "error": "UserNameTooShort"
* }
*/
// ------------------------------------------------------------------------------------------
// Current Permissions.
// ------------------------------------------------------------------------------------------
/**
* @apiDefinePermission admin Admin access rights needed.
* Optionally you can write here further Informations about the permission.
*
* An "apiDefinePermission"-block can have an "apiVersion", so you can attach the block to a specific version.
*
* @apiVersion 0.3.0
*/
// ------------------------------------------------------------------------------------------
// History.
// ------------------------------------------------------------------------------------------
/**
* @apiDefinePermission admin This title is visible in version 0.1.0 and 0.2.0
* @apiVersion 0.1.0
*/
/**
* @api {get} /user/:id Read data of a User
* @apiVersion 0.2.0
* @apiName GetUser
* @apiGroup User
* @apiPermission admin
*
* @apiDescription Here you can describe the function.
* Multilines are possible.
*
* @apiParam {String} id The Users-ID.
*
* @apiSuccess {String} id The Users-ID.
* @apiSuccess {Date} name Fullname of the User.
*
* @apiError UserNotFound The id of the User was not found.
*/
/**
* @api {get} /user/:id Read data of a User
* @apiVersion 0.1.0
* @apiName GetUser
* @apiGroup User
* @apiPermission admin
*
* @apiDescription Here you can describe the function.
* Multilines are possible.
*
* @apiParam {String} id The Users-ID.
*
* @apiSuccess {String} id The Users-ID.
* @apiSuccess {Date} name Fullname of the User.
*
* @apiError UserNotFound The error description text in version 0.1.0.
*/
/**
* @api {post} /user Create a User
* @apiVersion 0.2.0
* @apiName PostUser
* @apiGroup User
* @apiPermission none
*
* @apiDescription In this case "apiUse" is defined and used.
* Define blocks with params that will be used in several functions, so you dont have to rewrite them.
*
* @apiParam {String} name Name of the User.
*
* @apiSuccess {String} id The Users-ID.
*
* @apiUse CreateUserError
*/- example.js
/**
* @api {get} /user/:id Read data of a User
* @apiVersion 0.3.0
* @apiName GetUser
* @apiGroup User
* @apiPermission admin
*
* @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.
*
* @apiParam {String} id The Users-ID.
*
* @apiExample Example usage:
* curl -i http://localhost/user/4711
*
* @apiSuccess {String} id The Users-ID.
* @apiSuccess {Date} registered Registration Date.
* @apiSuccess {Date} name Fullname of the User.
* @apiSuccess {String[]} nicknames List of Users nicknames (Array of Strings).
* @apiSuccess {Object} profile Profile data (example for an Object)
* @apiSuccess {Number} profile.age Users age.
* @apiSuccess {String} profile.image Avatar-Image.
* @apiSuccess {Object[]} options List of Users options (Array of Objects).
* @apiSuccess {String} options.name Option Name.
* @apiSuccess {String} options.value Option Value.
*
* @apiError NoAccessRight Only authenticated Admins can access the data.
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Response (example):
* HTTP/1.1 401 Not Authenticated
* {
* "error": "NoAccessRight"
* }
*/
function getUser() { return; }
/**
* @api {post} /user Create a new User
* @apiVersion 0.3.0
* @apiName PostUser
* @apiGroup User
* @apiPermission none
*
* @apiDescription In this case "apiUse" is defined and used.
* Define blocks with params that will be used in several functions, so you dont have to rewrite them.
*
* @apiParam {String} name Name of the User.
*
* @apiSuccess {String} id The new Users-ID.
*
* @apiUse CreateUserError
*/
function postUser() { return; }
/**
* @api {put} /user/:id Change a new User
* @apiVersion 0.3.0
* @apiName PutUser
* @apiGroup User
* @apiPermission none
*
* @apiDescription This function has same errors like POST /user, but errors not defined again, they were included with "apiUse"
*
* @apiParam {String} name Name of the User.
*
* @apiUse CreateUserError
*/
function putUser() { return; }- apidoc.json
{
"name": "apidoc-example",
"version": "0.3.0",
"description": "apiDoc example project",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1",
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
},
"order": [
"GetUser",
"PostUser"
],
"template": {
"withCompare": true,
"withGenerator": true
}
}4. apiDoc参数
结构参数：
@apiDefine：用于定义一个可重用的文档块，这个文档块可以包含一段正常的接口文档，使用@apiDefine允许你组织更复杂的文档避免复制重复的块。
定义块可以有所有参数（像@apiParam），除了定义其他块。
具体来看每个参数：
@api
@api {method} path [title]注意：
- 如果没有这个指示器，apiDoc语法分析器会忽略文档块。只有一个情况例外，如果文档块是通过
@apiDefine定义的就不需要@api。
- 如果没有这个指示器，apiDoc语法分析器会忽略文档块。只有一个情况例外，如果文档块是通过
用法：
@api {get} /user/:id Users unique ID.Name Description method 请求方法名称：DELETE、GET、POST、PUT…，更多信息请参考：Wikipedia HTTP-Request_methods path 请求路径 title optional可选项，简短的标题，用于导航和文章头部 示例：
/** * @api {get} /user/:id */
@apiDefine
@apiDefine name [title]
[description]注意：
定义要嵌入在
@api块中的文档块，或者是一个像@apiPermission的api功能。@apiDefine每个块只能用一次。使用
@apiUse将导入定义的块，或使用名称、标题和描述。
用法：
@apiDefine MyErrorName Description name 块或值得唯一名称，相同名称使用 @apiVersion来区分。title optional可选项，简短的标题，仅用于功能名称像 @apiPermission或@apiParam (name)description optional可选项，在下一行开始的详细描述，可以是多行，仅用于功能名称像 @apiPermission示例：
/** * @apiDefine MyError * @apiError UserNotFound Theidof the User was not found. */ /** * @api {get} /user/:id * @apiUse MyError */ /** * @apiDefine admin User access only * This optional description belong to to the group admin. */ /** * @api {get} /user/:id * @apiPermission admin */获取更多细节请参考：inherit example
@apiDeprecated
@apiDeprecated [text]注意：
- 标记API方法不建议使用。
用法：
@apiDeprecated use now (#Group:Name).Name Description text 多行文本 示例：
/** * @apiDeprecated */ /** * @apiDeprecated use now (#Group:Name). * * Example: to set a link to the GetDetails method of your group User * write (#User:GetDetails) */
@apiDescription
@apiDescription text注意：
- API方法的详细描述。
用法：
@apiDescription This is the Description.Name Description text Multiline description text. 示例：
/** * @apiDescription This is the Description. * It is multiline capable. * * Last line of Description. */
@apiError
@apiError [(group)] [{type}] field [description]注意：
- 错误返回参数。
用法：
@apiError UserNotFoundName Description (group) optional可选项，所有参数将按这个名称分组。没有分组的，默认设置为 Error 4xx，你可以通过@apiDefine设置一个标题和描述。{type} optional可选项，返回类型，eg： {Boolean}、{Number}、{String}、{Object}、{String[]}（字符串数组）…field 返回标识符（返回错误码） description optionalfield的描述信息 示例：
/** * @api {get} /user/:id * @apiError UserNotFound Theidof the User was not found. */
@apiErrorExample
@apiErrorExample [{type}] [title]
example注意：
- 返回错误信息的示例，作为预格式化代码输出。
用法：
@apiErrorExample {json} Error-Response: This is an example.Name Description type optional响应格式 title optional示例的简短标题 example 详细示例，可以是多行 示例：
/** * @api {get} /user/:id * @apiErrorExample {json} Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */
@apiExample
@apiExample [{type}] title
example注意：
API请求方法的使用示例，作为预格式化代码输出。
在端点描述开始时使用它作为一个完整的例子。
用法：
@apiExample {js} Example usage: This is an example.Name Description type optional可选项，代码语言 title 示例的简短标题 example 详细示例，可以是多行 示例：
/** * @api {get} /user/:id * @apiExample {curl} Example usage: * curl -i http://localhost/user/4711 */
@apiGroup
@apiGroup name注意：
应该经常使用。
定义文档块属于哪个分组的方法。分组将用于生成输出文档的主导航，结构定义不需要
@apiGroup。
用法：
@apiGroup UserName Description name 分组名称，也可以用于导航标题 示例：
/** * @api {get} /user/:id * @apiGroup User */
@apiHeader
@apiHeader [(group)] [{type}] [field=defaultValue] [description]注意：
描述一个传递给API头部的参数，eg：Authorization
和
@apiParam类似，只有输出高于参数。
用法：
@apiHeader (MyHeaderGroup) {String} authorization Authorization value.Name Description (group) optional所有参数都会根据这个名称进行分组，如果没有分组，默认设置为 Parameter，你可以通过@apiDefine来设置标题和描述{type} optional参数类型，eg： {Boolean}、{Number}、{String}、{Object}、{String[]}（字符串数组）…field 变量名 [field] 带括号的变量名代表定义的变量是可选的 =defaultValue optional参数默认值 description optional描述字段 示例：
/** * @api {get} /user/:id * @apiHeader {String} access-key Users unique access-key.
@apiHeaderExample
@apiHeaderExample [{type}] [title]
example注意：
- 请求参数示例。
用法：
@apiHeaderExample {json} Request-Example: {"content": "This is an example content"}Name Description type optional请求格式 title optional示例的简短标题 example 详细示例，可以是多行 示例：
/** * @api {get} /user/:id * @apiHeaderExample {json} Header-Example: * { * "Accept-Encoding": "Accept-Encoding: gzip, deflate" * } */
@apiIgnore
@apiIgnore [hint]注意：
把它放在块顶部。
如果一个块是以
@apiIgnore开头将不会被解析，它是很有用的，如果你在源代码中留下过时或未完成的方法，并且不想将其发布到文档中，就可以采用此方法。
用法：
@apiIgnore Not finished MethodName Description hint optional这段块为什么要忽略的简短描述 示例：
/** * @apiIgnore Not finished Method * @api {get} /user/:id */
@apiName
@apiName name注意：
要经常使用。
定义文档块的名称。名称用来在生成的文档中作为子导航使用，定义结构不需要
@apiName。
用法：
@apiName GetUserName Description name 方法的唯一名称，相同名称需要通过 @apiVersion来区分。格式：method + path（eg：Get + User），这只是个建议，当然了，你可以随意命名。同样也是用于导航标题示例：
/** * @api {get} /user/:id * @apiName GetUser */
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]注意：
- 描述一个API请求方法传递的参数。
用法：
@apiParam (MyGroup) {Number} id Users unique ID.Name Description (group) optional所有的参数将会通过此名称分组。未分组的，默认设置为 Parameter，你可以通过@apiDefine设置标题和描述{type} optional参数类型，eg： {Boolean}、{Number}、{String}、{Object}、{String[]}（字符串数组）…{type{size}} optional关于变量大小的信息。 {string{..5}}代表一个最大只有5个字符的字符串类型，{string{2..5}}代表一个最小是2个字符最大是5个字符的字符串类型，{number{100-999}}代表取值范围为100-999的数值类型{type=allowedValues} optional关于变量允许值得信息。 {string="small"}代表字符串的值只能是small常量，{string="small","huge"}代表字符串只能包含small或者huge，{number=1,2,3,99}代表数值只能是1,2,3和99，可以和变量大小结合：{string {..5}="small", "huge"}代表一个字符串最大包含5个字符并且包含的值只能是small或者hugefield 变量名 [field] 带括号的文件名将变量定义为可选的 =defaultValue optional参数默认值 description optional描述字段 示例：
/** * @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} contry="DE" Mandatory with default value "DE". * @apiParam {Number} [age=18] Optional Age with default 18. * * @apiParam (Login) {String} pass Only logged in uesers can post this. * In generated documentation a separate * "Login" Block will be generated. */
@apiParamExample
@apiParamExample [{type}] [title]
example注意：
- 请求参数示例。
用法：
@apiParamExample {json} Request-Example: {"content": "This is an example content"}Name Description type optional请求格式 title optional示例的简短标题 example 详细示例，可以是多行 示例：
/** * @api {get} /user/:id * @apiParamExample {json} Reuqst-Example: * { * "id": 4711 * } */
@apiPermission
@apiPermission name注意：
- 输出许可名。如果名称是通过
@apiDefine定义的，生成的文档包括附加标题和描述。
- 输出许可名。如果名称是通过
用法：
@apiPermission adminName Description name 许可的唯一命名 示例：
/** * @api {get} /user/:id * @apiPermission none */
@apiPrivate
@apiPrivate注意：
- 将API定义为私有的，允许创建两个API规范文档：一个不包含私有API，一个包含。
用法：
@apiPrivate命令行里的使用方法，是否包含私有API：
--private false|true示例：
/** * @api {get} /user/:id * @apiPrivate */
@apiSampleRequest
@apiSampleRequest url注意：
与apidoc.json配置参数
sampleUrl一起使用此参数。如果sampleUrl设置了，所有请求方法都会包含一个api测试功能（将会追加@api在端点）。如果没有配置
sampleUrl，那么只有绑定了@apiSampleRequest的方法会有测试功能。如果
@apiSampleRequest url设置在了一个方法块内，那么这个url将会用来作为请求URL使用（当它以http开头会重写sampleUrl）。如果设置了
sampleUrl然后又不想给方法设置请求功能，可以在增加@apiSampleRequest off到文档块中。
用法：
@apiSampleRequest http://test.github.comName Description url API测试的服务器地址。 - 重写配置文件参数 sampleUrl并且追加@api地址：@apiSampleRequest http://www.example.com- 添加 @api地址前缀：@apiSampleRequst /my_test_path- 禁用API测试功能如果配置参数 sampleUrl设置为：@apiSampleRequest off示例：
- 将会发送API请求到：http://api.github.com/user/:id
Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id */- 将会发送API请求到：http://test.github.com/some_path/user/:id
Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id * @apiSampleRequest http://test.github.com/some_path/ */将会发送API请求到：http://api.github.com/test/user/:id
它其实是扩展了sampleUrl
Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id * @apiSampleRequest /test */- 将会禁用API方法的的API请求
Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id * @apiSampleRequest off */将会发送API请求到：http://api.github.com/some_path/user/:id
由于sampleUrl没有设置，所以它只激活该方法的请求
Configuration parameter sampleUrl is not set /** * @api {get} /user/:id * @apiSampleRequest http://api.github.com/some_path/ */
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]注意：
- 成功返回的参数。
用法：
@apiSuccess {String} firstname Firstname of the User.Name Description (group) optional所有的参数将会通过此名称分组。未分组的，默认设置为 Success 200，你可以通过@apiDefine设置标题和描述{type} optional参数类型，eg： {Boolean}、{Number}、{String}、{Object}、{String[]}（字符串数组）…field 返回的标识符（返回成功码） description optional可选项，描述字段 示例：
/** * @api {get} /user/:id * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */- 以
group分组为例，详细的分组示例请参考：@apiSuccessTitle：
/** * @api {get} /user/:id * @apiSuccess (200) {String} firstname Firstname of the User. * @apiSuccess (200) {String} lastname Lastname of the User. */- 以
Object为例：
/** * @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. */- 以
Array为例：
/** * @api {get} /users * @apiSuccess {Object[]} profiles List of user profiles. * @apiSuccess {Number} profiles.age Users age. * @apiSuccess {String} profiles.image Avatar-Image. */- 以
@apiSccessExample
@apiSuccessExample [{type}] [title]
example注意：
- 成功返回的信息示例，作为预格式化代码输出。
用法：
@apiSuccessExample {json} Success-Response: {"content": "This is an example content"}Name Description type optional响应格式 title optional示例的简短标题 example 详细示例，可以是多行 示例：
/** * @api {get} /user/:id * @apiSuccessExample {json} Success-Resopnse: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } */
@apiUse
@apiUse name注意：
- 包含使用
@apiDefine定义的块，如果与@apiVersion一起使用，将包含相同或最近的版本。
- 包含使用
用法：
@apiUse MySuccessName Description name 定义的块名称 示例：
/** * @apiDefine MySuccess * @apiSuccess {string} firstname the users firstname. * @apiSuccess {number} age The users age. */ /** * @api {get} /user/:id * @apiUse MySuccess */
@apiVersion
@apiVersion version注意：
设置文档块的版本。版本同样可以用于
@apiDefine。如果文档块有相同的分组和名称，但是版本不同，也可以在输出文档中进行对比。所以如果你是一个前端开发人员，可以追溯自上个版本以来API中发生了哪些更改。
用法：
@apiVersion 1.6.2Name Description version 支持简单的版本（格式为：主版本.次版本.补丁版本），更多信息请参考：Semantic Versioning Specification(SemVer). 示例：
/** * @api {get} /user/:id * @apiVersion 1.6.2 */更多请参考：versioning example