摘要：前言說(shuō)明是一個(gè)文檔生成工具可以根據(jù)代碼注釋生成文檔從注釋生成靜態(tài)網(wǎng)頁(yè)文檔，不僅支持項(xiàng)目版本號(hào)，還支持版本號(hào)安裝系統(tǒng)需要安裝略安裝有些系統(tǒng)需要權(quán)限來(lái)安裝執(zhí)行生成這個(gè)文檔的生成規(guī)則是對(duì)于項(xiàng)目中我們使用封裝了一個(gè)函數(shù)生成文檔注意分組名不

說(shuō)明
apidoc是一個(gè)API文檔生成工具, apidoc可以根據(jù)代碼注釋生成web api文檔, apidoc從注釋生成靜態(tài)html網(wǎng)頁(yè)文檔，不僅支持項(xiàng)目版本號(hào)，還支持api版本號(hào)

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

B). 安裝apidoc

# 有些系統(tǒng)需要sudo 權(quán)限來(lái)安裝
$ npm install apidoc -g

C). 執(zhí)行生成

# 這個(gè)文檔的生成規(guī)則是 
# apidoc 
#      -i code_dir
#      -o output_dir
$ apidoc -i myapp/ -o apidoc/ 

# 對(duì)于項(xiàng)目中我們使用 laravel artisan 封裝了一個(gè)函數(shù)
# 生成 api doc 文檔
$ php artisan lemon:doc apidoc

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

A) 生成文檔

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

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

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

默認(rèn)會(huì)帶上-c，在當(dāng)前路徑下尋找配置文件 apidoc.json，如果找不到則會(huì)在package.json中尋找 "apidoc": { } 

-f 為文件過(guò)濾，后面是正則表達(dá)式，示例為只選著js文件 

-e 的選項(xiàng)，表示要排除的文件/文件夾，也是使用正則表達(dá)式

B) 項(xiàng)目配置

{
    "name" : "項(xiàng)目名",
    "version": "1.0.0",
    "title": "mysails-瀏覽器標(biāo)題",
    "description": "description"
}

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

apidoc 支持如下關(guān)鍵字：(下面 [ ] 中括號(hào)中表示是可選寫(xiě)的內(nèi)容，使用時(shí)不用加 [ ] 中括號(hào)。)

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

@apiName name
    接口名稱，在同一個(gè)@apiGroup下，名稱相同的@api通過(guò)@apiVersion區(qū)分，否者后面@api會(huì)覆蓋前面定義的@api

@apiDescription text
    接口描述，支持html語(yǔ)法

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

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

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

@apiSuccess [(group)] [{type}] field [description]
    用法基本類似，分別描述請(qǐng)求參數(shù)、頭部，響應(yīng)錯(cuò)誤和成功
    group表示參數(shù)的分組，type表示類型(不能有空格)，入?yún)⒖梢远x默認(rèn)值(不能有空格)，field上使用[]中擴(kuò)號(hào)表示該參數(shù)是可選參數(shù)
    
@apiParamExample [{type}] [title] example

@apiHeaderExample [{type}] [title] example

@apiErrorExample [{type}] [title] example

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

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

apiName 的命名規(guī)范是 apiGroup + functionName;

apiName 的寫(xiě)法規(guī)范是 首字母大寫(xiě)的駝峰模式

例如上面的命名規(guī)范是

apiGroup : Home
apiName  : HomeCheckVerification

數(shù)字類型, 需要轉(zhuǎn)換成int 類型(返回的json 串中不需要有引號(hào)包裹)

文字類型的, 需要轉(zhuǎn)換成 string 類型

返回值中不允許存在 null

返回的類型值, 參數(shù)值, 說(shuō)明必須對(duì)齊

返回的參數(shù)值和真正返回的內(nèi)容值必須填寫(xiě)完整

/**
 * @api                 {get} /api_prefix/version [O]檢測(cè)新版本(Android)
 * @apiVersion          1.0.0
 * @apiName             HomeVersion
 * @apiGroup            Home
 * @apiParam   {String}  version        版本號(hào)
 * @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
    ...

系統(tǒng)使用 dinggo 作為 api的封裝組件

dingo/api 中文文檔

A). 接口命名

lists   => 列表
create  => 創(chuàng)建
edit    => 編輯
delete  => 刪除

B). 參數(shù)命名

例如 A下的傳遞參數(shù), 我們應(yīng)當(dāng)使用  title 而不能使用

C). 路由命名

路由的名稱和坐在分組還有函數(shù)名進(jìn)行匹配, 使用蛇形寫(xiě)法

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

這里的命名是 api_dailian.bank_lists

D). 自營(yíng)的接口無(wú)特殊返回不需要填寫(xiě)說(shuō)明

E). 接口中只能返回有意義的數(shù)據(jù), 對(duì)app無(wú)用的數(shù)據(jù)不得返回

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