1.特點(diǎn)：

1. apidoc是根據(jù)你源代碼中的API注釋生成的文檔 ，一行命令即可生成api接口文檔
2. 此api文檔集成了各個(gè)版本API，清晰的顯示了各個(gè)版本之間的對(duì)比
3. 可隨意查看不同版本的api
4. 擁有強(qiáng)大的接口測(cè)試功能，只要填寫參數(shù)，即可查看響應(yīng)數(shù)據(jù)

2.安裝前準(zhǔn)備

1. 安裝node
2. 安裝node的npm
3. 用npm安裝apidoc
   npm install apidoc -g

3.使用教程

前提是你的源碼中已經(jīng)編寫了api的接口注釋
apidoc -i yourProjectFile -o apidoc
yourProjectFile 你自己的項(xiàng)目文件夾

apidoc生成的web形式的api文檔
文檔入口apidoc/index.html

（以下demo主要以java代碼來演示，其他語言也給了出示例）

3.1 項(xiàng)目中如何編寫接口注釋

java注釋

/** 
* 這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結(jié)尾給出）
*/

CoffeeScript 注釋

###
 這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結(jié)尾給出）
###

Elixir

@apidoc """
 這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結(jié)尾給出）
"""

Erlang (% within the comment is optional)注釋

%{
%  這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結(jié)尾給出）
%}

Perl (Oxygen)注釋

#**
#  這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結(jié)尾給出）
#*

Python注釋

"""
 這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結(jié)尾給出）
"""

Ruby注釋

=begin
 這部分寫接口注釋內(nèi)容（完整的注釋模板在本文結(jié)尾給出）
=end

3.2 項(xiàng)目中可以通過配置，來設(shè)置注釋的模板，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]

3.3.2 @apiDefine 自定義api屬性模板

格式：`@apiDefine name [title] [description]
下面的例子是自定義的@apiError 當(dāng)然你可以自定義其他屬性@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

一個(gè)項(xiàng)目可能有不同的版本，對(duì)應(yīng)的API可能也有不同的版本，添加這個(gè)屬性就可以根據(jù)版本來選擇對(duì)應(yīng)的API了，
！！！代碼中的一個(gè)注釋對(duì)應(yīng)一個(gè)api接口，例如：login接口在源碼中的注釋有兩個(gè)，版本分別是
@ apiVersion =0.2.0
@ apiVersion =0.2.1
那么生成的api文檔才會(huì)有兩個(gè)版本的對(duì)比，如果源碼中只有一個(gè)版本login的注釋，那么API文檔中也只有一個(gè)接口顯示，就沒有版本對(duì)比

下圖是API兩個(gè)版本的對(duì)比。
相對(duì)于0.2.0的版本新增了fileAdd字段是綠色。
刪除了firstName標(biāo)注成了紅色

0.2.1相對(duì)與0.2.0版本API的差異

3.3.4 @apiName name 接口名

但是在html格式的文檔中不會(huì)顯示，導(dǎo)航欄中的接口標(biāo)題是在@apidoc屬性中設(shè)置的
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 這個(gè)接口是用來獲取用戶信息的（這是關(guān)于接口的描述內(nèi)容）
 */

3.3.6 @apiParam API的請(qǐng)求參數(shù)

@apiParam [(group)] [{type}] [field=defaultValue] [description]

3.3.7 @apiParamExample 請(qǐng)求參數(shù)示例

這個(gè)是參數(shù)的具體請(qǐng)求格式的一個(gè)例子，主要針對(duì)json類型的數(shù)據(jù),格式如下
@apiParamExample [{type}] [title] example

/** 
 * @api {get} /user/:id 
 * @apiParamExample {json} Request-Example:
 *  {
 *    "id": 4711 
 *  } 
 */

3.3.8 @apiError api 請(qǐng)求出錯(cuò)返回字段說明

格式：@apiError [(group)] [{type}] field [description]
Example：

/** 
 * @api {get} /user/:id 
 * @apiError UserNotFound   The <code>id</code> not found   
 * @apiError token     <code>token</code>   錯(cuò)誤
 */

3.3.9 @apiErrorExample Error-Response: api請(qǐng)求錯(cuò)誤返回?cái)?shù)據(jù)示例

格式：@apiErrorExample [{type}] [title] example
請(qǐng)求失敗返回的數(shù)據(jù)(json格式)
Example：

/** 
* @api {get} /user/:id 
* @apiErrorExample {json} Error-Response: 
* HTTP/1.1 404 Not Found
 * {
 * "error": "UserNotFound" 
* }
 */

類似的 @apiSuccess 是請(qǐng)求成功以后的字段含義說明

@apiSuccessExample 是請(qǐng)求成功后的響應(yīng)數(shù)據(jù)

用法一致，只是名字不同

3.3.10 @apiSampleRequest 接口請(qǐng)求示例

這個(gè)功能可謂這個(gè)文檔中一個(gè)強(qiáng)大的功能,如下

Example:

 * @apiParam {String} token  搜索內(nèi)容
 * @apiSampleRequest   http://your_api_url

設(shè)置了參數(shù)以及url生成的html中即可看到效果

@apiSampleRequest屬性使用

3.3.10 @apiIgnore 隱藏api

格式： @apiIgnore [hint]
這個(gè)屬性用于開發(fā)人員還沒有完全編寫好的接口，如果不想顯示在html文檔中那么就使用這個(gè)屬性
Example:

/** 
 * @apiIgnore 這個(gè)接口暫時(shí)還沒有開發(fā)完，暫時(shí)不顯示
 * @api {get} /user/:id
  */

3.3.11 @apiHeader

HTTP Header中Accept-Encoding 是瀏覽器發(fā)給服務(wù)器,聲明瀏覽器支持的編碼類型
格式：@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

更多請(qǐng)參照官方文檔 http://apidocjs.com/#param-api-use、

有待完善，暫時(shí)就整理這些吧