1.特點：
- apidoc是根據(jù)你源代碼中的API注釋生成的文檔 性穿，一行命令即可生成api接口文檔
- 此api文檔集成了各個版本API佩研，清晰的顯示了各個版本之間的對比
- 可隨意查看不同版本的api
- 擁有強大的接口測試功能，只要填寫參數(shù)算利，即可查看響應數(shù)據(jù)
2.安裝前準備
- 安裝node
- 安裝node的npm
- 用npm安裝apidoc
npm install apidoc -g
3.使用教程
前提是你的源碼中已經(jīng)編寫了api的接口注釋
apidoc -i yourProjectFile -o apidoc
yourProjectFile 你自己的項目文件夾
apidoc生成的web形式的api文檔
文檔入口apidoc/index.html
（以下demo主要以java代碼來演示悍手，其他語言也給了出示例）
3.1 項目中如何編寫接口注釋
java注釋
/**
* 這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結尾給出）
*/
CoffeeScript 注釋
###
這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結尾給出）
###
Elixir
@apidoc """
這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結尾給出）
"""
Erlang (% within the comment is optional)注釋
%{
% 這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結尾給出）
%}
Perl (Oxygen)注釋
#**
# 這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結尾給出）
#*
Python注釋
"""
這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結尾給出）
"""
Ruby注釋
=begin
這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結尾給出）
=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可能也有不同的版本香罐，添加這個屬性就可以根據(jù)版本來選擇對應的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 這個接口是用來獲取用戶信息的（這是關于接口的描述內(nèi)容）
*/
3.3.6 @apiParam API的請求參數(shù)
@apiParam [(group)] [{type}] [field=defaultValue] [description]
| 名稱 | 含義 |
|---|---|
| group （可選） | 請求方法的名稱DELETE, GET, POST, PUT |
| {type} （可選） | 參數(shù)類型{Boolean}, {Number}, {String}, {Object}, {String[]}覆醇，(array of strings) |
| {type{size}} （可選） | 變量的范圍 {string{..5}}這個字符串最多5個字符 {string{2..5}}這個字符串最少2個字符，最多5個字符 {number{100-999}} 在100到999之間的數(shù)字 |
| {type=allowedValues}(可選) | 參數(shù)的可選值 {number=1,2,3,99} 這個數(shù)字的值只能是其中之一 {string="small","huge"} 這個字符串的值只能是small或者huge {number=1,2,3,99} 這個數(shù)字的值只能是其中之一 |
| field | 字段名 |
| defaultValue | 字段的默認值 |
| description | 字段的描述（這個字段的含義） |
3.3.7 @apiParamExample 請求參數(shù)示例
這個是參數(shù)的具體請求格式的一個例子炭臭，主要針對json類型的數(shù)據(jù),格式如下
@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請求錯誤返回數(shù)據(jù)示例
格式：@apiErrorExample [{type}] [title] example
請求失敗返回的數(shù)據(jù)(json格式)
Example：
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
類似的 @apiSuccess 是請求成功以后的字段含義說明
@apiSuccessExample 是請求成功后的響應數(shù)據(jù)
用法一致永脓，只是名字不同
3.3.10 @apiSampleRequest 接口請求示例
這個功能可謂這個文檔中一個強大的功能,如下
Example:
* @apiParam {String} token 搜索內(nèi)容
* @apiSampleRequest http://your_api_url
設置了參數(shù)以及url生成的html中即可看到效果
3.3.10 @apiIgnore 隱藏api
格式： @apiIgnore [hint]
這個屬性用于開發(fā)人員還沒有完全編寫好的接口，如果不想顯示在html文檔中那么就使用這個屬性
Example:
/**
* @apiIgnore 這個接口暫時還沒有開發(fā)完鞋仍，暫時不顯示
* @api {get} /user/:id
*/
3.3.11 @apiHeader
HTTP Header中Accept-Encoding 是瀏覽器發(fā)給服務器,聲明瀏覽器支持的編碼類型
格式：@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常摧、
有待完善，暫時就整理這些吧
