1.特点：
- apidoc是根据你源代码中的API注释生成的文档 ，一行命令即可生成api接口文档
- 此api文档集成了各个版本API，清晰的显示了各个版本之间的对比
- 可随意查看不同版本的api
- 拥有强大的接口测试功能，只要填写参数，即可查看响应数据
2.安装前准备
- 安装node
- 安装node的npm
- 用npm安装apidoc
npm install apidoc -g
3.使用教程
前提是你的源码中已经编写了api的接口注释
apidoc -i yourProjectFile -o apidoc
yourProjectFile 你自己的项目文件夹
apidoc生成的web形式的api文档
文档入口apidoc/index.html
（以下demo主要以java代码来演示，其他语言也给了出示例）
3.1 项目中如何编写接口注释
java注释
/**
* 这部分写接口注释内容（完整的注释模板在本文结尾给出）
*/
CoffeeScript 注释
###
这部分写接口注释内容（完整的注释模板在本文结尾给出）
###
Elixir
@apidoc """
这部分写接口注释内容（完整的注释模板在本文结尾给出）
"""
Erlang (% within the comment is optional)注释
%{
% 这部分写接口注释内容（完整的注释模板在本文结尾给出）
%}
Perl (Oxygen)注释
#**
# 这部分写接口注释内容（完整的注释模板在本文结尾给出）
#*
Python注释
"""
这部分写接口注释内容（完整的注释模板在本文结尾给出）
"""
Ruby注释
=begin
这部分写接口注释内容（完整的注释模板在本文结尾给出）
=end
3.2 项目中可以通过配置，来设置注释的模板，java中代码的注释如下
/**
* @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"
* }
*/
3.3下面逐一解释上面的属性
3.3.1 @apidoc
@api {method} path [title]
| 名称 | 含义 |
|---|---|
| method | 请求方法的名称DELETE, GET, POST, PUT |
| path | 请求的路径 |
| title | api名称，会在导航栏中显示 |
3.3.2 @apiDefine 自定义api属性模板
格式：`@apiDefine name [title] [description]
下面的例子是自定义的@apiError 当然你可以自定义其他属性@apiPermission ，@apiSuccess或者其他属性，如下一次定义，不同api都可以引用，
引用方式 * @apiUse UserNotFoundError
Example:
/**
* @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
*/
3.3.3 @ apiVersion
一个项目可能有不同的版本，对应的API可能也有不同的版本，添加这个属性就可以根据版本来选择对应的API了，
！！！代码中的一个注释对应一个api接口，例如：login接口在源码中的注释有两个，版本分别是
@ apiVersion =0.2.0
@ apiVersion =0.2.1
那么生成的api文档才会有两个版本的对比，如果源码中只有一个版本login的注释，那么API文档中也只有一个接口显示，就没有版本对比
下图是API两个版本的对比。
相对于0.2.0的版本新增了fileAdd字段是绿色。
删除了firstName标注成了红色
3.3.4 @apiName name 接口名
但是在html格式的文档中不会显示，导航栏中的接口标题是在@apidoc属性中设置的
Example：
/**
* @api {get} /user/:id
* @apiName GetUser
*/
3.3.4 @apiGroup API接口的分组，例如 登录api和获取用户信息api都是用户模块
Example：
/**
* @api {get} /user/:id
* @apiGroup User
*/
3.3.5 apiDescription 接口描述
@apiDescription text
Example：
/**
* @apiDescription 这个接口是用来获取用户信息的（这是关于接口的描述内容）
*/
3.3.6 @apiParam API的请求参数
@apiParam [(group)] [{type}] [field=defaultValue] [description]
| 名称 | 含义 |
|---|---|
| group （可选） | 请求方法的名称DELETE, GET, POST, PUT |
| {type} （可选） | 参数类型{Boolean}, {Number}, {String}, {Object}, {String[]}，(array of strings) |
| {type{size}} （可选） | 变量的范围 {string{..5}}这个字符串最多5个字符 {string{2..5}}这个字符串最少2个字符，最多5个字符 {number{100-999}} 在100到999之间的数字 |
| {type=allowedValues}(可选) | 参数的可选值 {number=1,2,3,99} 这个数字的值只能是其中之一 {string="small","huge"} 这个字符串的值只能是small或者huge {number=1,2,3,99} 这个数字的值只能是其中之一 |
| field | 字段名 |
| defaultValue | 字段的默认值 |
| description | 字段的描述（这个字段的含义） |
3.3.7 @apiParamExample 请求参数示例
这个是参数的具体请求格式的一个例子，主要针对json类型的数据,格式如下
@apiParamExample [{type}] [title] example
/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
3.3.8 @apiError api 请求出错返回字段说明
格式：@apiError [(group)] [{type}] field [description]
Example：
/**
* @api {get} /user/:id
* @apiError UserNotFound The <code>id</code> not found
* @apiError token <code>token</code> 错误
*/
3.3.9 @apiErrorExample Error-Response: api请求错误返回数据示例
格式：@apiErrorExample [{type}] [title] example
请求失败返回的数据(json格式)
Example：
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
类似的 @apiSuccess 是请求成功以后的字段含义说明
@apiSuccessExample 是请求成功后的响应数据
用法一致，只是名字不同
3.3.10 @apiSampleRequest 接口请求示例
这个功能可谓这个文档中一个强大的功能,如下
Example:
* @apiParam {String} token 搜索内容
* @apiSampleRequest http://your_api_url
设置了参数以及url生成的html中即可看到效果
3.3.10 @apiIgnore 隐藏api
格式： @apiIgnore [hint]
这个属性用于开发人员还没有完全编写好的接口，如果不想显示在html文档中那么就使用这个属性
Example:
/**
* @apiIgnore 这个接口暂时还没有开发完，暂时不显示
* @api {get} /user/:id
*/
3.3.11 @apiHeader
HTTP Header中Accept-Encoding 是浏览器发给服务器,声明浏览器支持的编码类型
格式：@apiHeader [(group)] [{type}] [field=defaultValue] [description]
Example:
/**
* @api {get} /user/:id
* @apiHeader {String} access-key Users unique access-key.
*/
3.3.12 @apiHeaderExample
@apiHeaderExample [{type}] [title] example
/**
* @api {get} /user/:id
* @apiHeaderExample {json} Header-Example:
* {
* "Accept-Encoding": "Accept-Encoding: gzip, deflate"
* }
*/
3.3.13 @apiUse 重用的文本模块
@apiUse name
/**
* @apiDefine MySuccess
* @apiSuccess {string} firstname The users firstname.
* @apiSuccess {number} age The users age.
*/
/**
* @api {get} /user/:id
* @apiUse MySuccess
*/
demo
http://download.csdn.net/detail/xubeiqiannian/9563098
更多请参照官方文档 http://apidocjs.com/#param-api-use、
有待完善，暂时就整理这些吧
