摘要：前言說明是一個文檔生成工具可以根據代碼注釋生成文檔從注釋生成靜態網頁文檔，不僅支持項目版本號，還支持版本號安裝系統需要安裝略安裝有些系統需要權限來安裝執行生成這個文檔的生成規則是對于項目中我們使用封裝了一個函數生成文檔注意分組名不

說明
apidoc是一個API文檔生成工具, apidoc可以根據代碼注釋生成web api文檔, apidoc從注釋生成靜態html網頁文檔，不僅支持項目版本號，還支持api版本號

A). 系統需要安裝nodejs(略)

B). 安裝apidoc

# 有些系統需要sudo 權限來安裝
$ npm install apidoc -g

C). 執行生成

# 這個文檔的生成規則是 
# apidoc 
#      -i code_dir
#      -o output_dir
$ apidoc -i myapp/ -o apidoc/ 

# 對于項目中我們使用 laravel artisan 封裝了一個函數
# 生成 api doc 文檔
$ php artisan lemon:doc apidoc

注意: 分組名不支持中文，可修改

A) 生成文檔

$ apidoc -i myapp/ -o doc/api [-c ./] -f ".*.js$" 

-i 表示輸入，后面是文件夾路徑 

-o 表示輸出，后面是文件夾路徑 

默認會帶上-c，在當前路徑下尋找配置文件 apidoc.json，如果找不到則會在package.json中尋找 "apidoc": { } 

-f 為文件過濾，后面是正則表達式，示例為只選著js文件 

-e 的選項，表示要排除的文件/文件夾，也是使用正則表達式

B) 項目配置

{
    "name" : "項目名",
    "version": "1.0.0",
    "title": "mysails-瀏覽器標題",
    "description": "description"
}

我們的配置存放在根目錄 package.json 文件中.

apidoc 支持如下關鍵字：(下面 [ ] 中括號中表示是可選寫的內容，使用時不用加 [ ] 中括號。)

@api {method} path [title]
    只有使用@api標注的注釋塊才會在解析之后生成文檔，title會被解析為導航菜單(@apiGroup)下的小菜單
    method可以有空格，如{POST GET}
  
@apiGroup name
    分組名稱，被解析為導航欄菜單

@apiName name
    接口名稱，在同一個@apiGroup下，名稱相同的@api通過@apiVersion區分，否者后面@api會覆蓋前面定義的@api

@apiDescription text
    接口描述，支持html語法

@apiParam [(group)] [{type}] [field=defaultValue] [description]
    詳細介紹見: http://apidocjs.com/#param-api-param
    
@apiVersion verison
    接口版本，major.minor.patch的形式
    
@apiIgnore [hint]
    apidoc會忽略使用@apiIgnore標注的接口，hint為描述
    
@apiSampleRequest url
  接口測試地址以供測試，發送請求時，@api method必須為POST/GET等其中一種
  
@apiDefine name [title] [description]
    定義一個注釋塊(不包含@api)，配合@apiUse使用可以引入注釋塊
    在@apiDefine內部不可以使用@apiUse
@apiUse name
     引入一個@apiDefine的注釋塊

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

@apiError [(group)] [{type}] field [description]

@apiSuccess [(group)] [{type}] field [description]
    用法基本類似，分別描述請求參數、頭部，響應錯誤和成功
    group表示參數的分組，type表示類型(不能有空格)，入參可以定義默認值(不能有空格)，field上使用[]中擴號表示該參數是可選參數
    
@apiParamExample [{type}] [title] example

@apiHeaderExample [{type}] [title] example

@apiErrorExample [{type}] [title] example

@apiSuccessExample [{type}] [title] example
    用法完全一致，但是type表示的是example的語言類型
  example書寫成什么樣就會解析成什么樣，所以最好是書寫的時候注意格式化，(許多編輯器都有列模式，可以使用列模式快速對代碼添加*號)

/**
 * @api                 {get} /api_prefix/check_verification [O]驗證驗證碼
 * @apiVersion          1.0.0
 * @apiName             HomeCheckVerification
 * @apiGroup            Home
 * @apiParam   {String} mobile       手機號
 * @apiParam   {String} captcha      驗證碼
 */
public function checkVerification(){}

apiName 的命名規范是 apiGroup + functionName;

apiName 的寫法規范是 首字母大寫的駝峰模式

例如上面的命名規范是

apiGroup : Home
apiName  : HomeCheckVerification

數字類型, 需要轉換成int 類型(返回的json 串中不需要有引號包裹)

文字類型的, 需要轉換成 string 類型

返回值中不允許存在 null

返回的類型值, 參數值, 說明必須對齊

返回的參數值和真正返回的內容值必須填寫完整

/**
 * @api                 {get} /api_prefix/version [O]檢測新版本(Android)
 * @apiVersion          1.0.0
 * @apiName             HomeVersion
 * @apiGroup            Home
 * @apiParam   {String}  version        版本號
 * @apiSuccess {String}  download_url   下載地址
 * @apiSuccess {String}  description    描述
 * @apiSuccess {String}  version        版本
 * @apiSuccessExample  data:
 * {
 *     "download_url": "http://domain.com/1.1.1.apk",
 *     "description": "修改bug若干, 增加微信支付功能",
 *     "version": "1.1.1"
 * }
 */
public function version()

api 路由文件存放在 app/Http/Routes/ 文件夾下

Routes/
    api_dailian.php
    api_up.php
    ...

系統使用 dinggo 作為 api的封裝組件

dingo/api 中文文檔

A). 接口命名

lists   => 列表
create  => 創建
edit    => 編輯
delete  => 刪除

B). 參數命名

例如 A下的傳遞參數, 我們應當使用  title 而不能使用

C). 路由命名

路由的名稱和坐在分組還有函數名進行匹配, 使用蛇形寫法

/**
 * @api                 {get} /dailian/bank/lists [O][B]銀行賬戶列表
 * @apiVersion          1.0.0
 * @apiName             UserBankList
 * @apiGroup            User
 * @apiSuccess {String} id                  賬號ID
 * @apiSuccess {String} bank_account        賬號信息
 * @apiSuccess {String} bank_true_name      真實姓名
 * @apiSuccess {String} bank_type           賬號類型 : 支付寶
 * @apiSuccess {String} note                備注
 * @apiSuccessExample   成功返回:
 *  [
 *      {
 *          "id": 2,
 *          "bank_account": "123123123",
 *          "bank_true_name": "二狗",
 *          "bank_type": "支付寶",
 *          "note": ""
 *      }
 *  ]
 */
public function lists()

這里的命名是 api_dailian.bank_lists

D). 自營的接口無特殊返回不需要填寫說明

E). 接口中只能返回有意義的數據, 對app無用的數據不得返回

F). 列表為空也需要返回分頁