整 理：曹燕
时 间：2015-11-27
说 明：Apidoc的安装及使用（官方文档：http://apidocjs.com/）
1.安装
2.运行
3.apidoc.json配置文件
4.注释中必需的部分
5.继承
6.apidoc的注释规则
（1）@api——定义接口的请求方式、请求路径、标题
（2）@apiDefine——定义一个可重用的块
（3）@apiDescription——api方法的详细介绍
（4）@apiError——出错情况的描述
（5）@apiErrorExample——一个返回出错信息的示例
（6）@apiExample——使用一个接口的示例
（7）@apiGroup——对块进行分类，便于导航条分类
（8）@apiHeader
（9）@apiHeaderExample
（10）@apiIgnore——不被转换的块
（11）@apiName——接口的名称
（12）@apiParam——描述接口的参数
（13）@apiParamExample——接口参数的一个示例
（14）@apiPermission
（16）@apiSuccess——成功时的返回值
（17）@apiSuccessExample——一个成功的返回信息的示例
（18）@apiUse——调用一个已经定义好的块
（19）@apiVersion——一个块的版本信息
1.安装
npm install apidoc -g
2.运行
apidoc -i myapp/ -o apidoc/ -t mytemplate/
-i 输入文件的目录，即项目文件夹
-o 输出目录，即放置生成文档的位置
-t 使用的模板，会有默认的模板，当然也可以用自己定义的模板
示例： apidoc -i abc/ -o doc/ 
3.apidoc.json配置文件
放在你的工程项目的根目录下，是对项目的概要介绍，包括标题、简要介绍、版本等。
{
"name": "育儿网",
"version": "1.0.0",
"description": "育儿API文档",
"title": "API文档",
"template": {
"withCompare": true,
"withGenerator": true
}
}
其中name、version、description都会被显示出来。
4.注释中必需的部分
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*/
- 注释块必须用/** */包围
- @api {get} /user/:id Request User information
注释块必须以@api开头，否则会忽视这个注释块
- @apiName必须是一个独一无二的名字
- @apiGroup的作用是给这个方法分组
5.继承
@apiDefine定义了一个可重用的块，然后其他块调用这个块的时候就写：
@apiUse UserNotFoundError
在生成的文档中会自动填充成UserNotFoundError块的具体内容。
Apidoc中的继承只能继承一层，层数多了会影响可读性。
6.apidoc的注释规则
（1）@api——定义接口的请求方式、请求路径、标题
【开头必需，除非是@apiDefine开头】
Method：必须，方法的请求方式，如get、post、put、delete...
Path：必须，请求路径
Title：可选，可选，用于导航和文章的子标题
（2）@apiDefine——定义一个可重用的块
Name：必须，独一无二的名字，之后引用这个块就是用这个名字
Title：可选，标题
Description：可选，详细介绍，另起一行写
（3）@apiDescription——api方法的详细介绍
Text：必须，api方法的文字介绍
（4）@apiError——出错情况的描述
(Group)：可选，有了group值之后该错误会被分组；默认归类为Error 4xx。
{Type}：可选，返回类型，如{Boolean}，{Number}，{String}等。
Field：必须，返回标识符，例如错误码。
Description：可选，对错误码的描述。
（5）@apiErrorExample——一个返回出错信息的示例
会以预格式化代码输出到页面
{type}：可选，返回信息的格式
Title：可选，这个出错信息的标题
Example：必须，具体的返回信息
（6）@apiExample——使用一个接口的示例
会以预格式化代码输出到页面
{type}：可选，代码的语言
Title：必须，这个例子的标题
Example：必须，使用接口的代码
（7）@apiGroup——对块进行分类，便于导航条分类
Name：必须，分类的名称
（8）@apiHeader
暂略
（9）@apiHeaderExample
暂略
（10）@apiIgnore——不被转换的块
将这句放在块的起始位置，这样进行转换的时候这个块就会被跳过，常常用于一个块还没有开发完毕的时候。
Hint：可选，描述为什么不转换这个块
（11）@apiName——接口的名称
Name：必须，接口的名称，必须是独一无二的名称（允许版本不同的同一名称）
（12）@apiParam——描述接口的参数
（group）：可选，所有的参数会被分到这个类里，如果不设置，就分到Parameter。
{type}：可选，参数的类型，如{String}等。
{type{size}}：可选，参数取值的详细信息，如
{number{100-999}}——参数必须是个100-999的数字
{string{2..5}}——参数必须是2-5个字符的字符串
{type=allowedValues}：可选，关于变量允许取值的信息，如
{string="small","huge"}——参数必须是包含”small”或”huge”的字符串
Field：必须，变量名，表示该参数对于接口是必须的
[field]：必须，变量名，表示该参数对于接口不是必须的
=defaultValue：可选，参数的默认取值
Description：可选，参数的描述
（13）@apiParamExample——接口参数的一个示例
{type}：可选，请求信息的格式
Title：可选，示例的标题
Example：必须，请求的具体信息
（14）@apiPermission
暂略
（15）@apiSampleRequest——模拟请求时的url
（16）@apiSuccess——成功时的返回值
（group）：可选，所有的参数会被分到这个类里，如果不设置，就分到Success 200。
{type}：可选，参数的类型，如{String}等。
Field：必须，返回标识符。
Description：可选，成功码的描述。
（17）@apiSuccessExample——一个成功的返回信息的示例
{type}：可选，返回信息的格式
Title：可选，示例的标题
Example：必须，返回的具体信息
（18）@apiUse——调用一个已经定义好的块
已经定义的块是指用@apiDefine定义的块
Name：必须，@apiDefine定义的块的名称
（19）@apiVersion——一个块的版本信息
Group和name值都相同的块，可以进行不同版本的对比。可用于在生成的文档中和之前的版本进行比较，增加和修改的会用绿色标出、删除的会用红色标出。
Version：必须，版本号
