整 理:曹燕
时 间: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:必须,版本号