詳細(xì)閱讀apiDoc官方文檔
- 詳細(xì)閱讀官方文檔：http://apidocjs.com
項(xiàng)目中apiDoc文件結(jié)構(gòu)
-
整體結(jié)構(gòu)
圖片 -
apidoc.json
圖片 -
common.php- 公共部分定義-權(quán)限（apiPermission）
-
定義
圖片 -
使用
圖片
-
- 公共部分定義-狀態(tài)碼分組（apiSuccess、apiError）
-
定義
圖片 -
使用
圖片
圖片
-
- 公共部分定義-錯(cuò)誤響應(yīng)（apiError、apiErrorExample）
-
定義
圖片 -
使用
圖片
-
- 公共部分定義-權(quán)限（apiPermission）
-
define.php- 公共部分定義-api分組
-
定義
圖片 -
使用
圖片
接口具體apidoc定義
接口最新定義在代碼實(shí)現(xiàn)處，歷史版本定義在apidoc/history.php中。
-
接口定義完整示例：
圖片 @apiVersion目前只用到major和minor，patch始終為0。
-
@apiName- 從
@api定義轉(zhuǎn)換而來(lái)：
如@api為：@api {put} /user/babies/:baby_id 修改寶寶信息，
則@apiName為:@apiName put/user/babies/:baby_id，
則解析后的ID為；put_user_babies__baby_id（用于apidoc.json的order接口排序）。
- 從
-
@apiGroup- 接口分組，定義在
apidoc/define.php，如@apiGroup babyGroup。
- 接口分組，定義在
-
@apiPermission- 接口權(quán)限，定義在
apidoc/common.php，權(quán)限分為：-
none：無(wú)需任何授權(quán)； -
token：需要用戶登錄授權(quán)，可通過(guò)header Authorization和Cookie HBSID傳遞； -
admintoken：需要管理員登錄授權(quán)，可通過(guò)header Authorization和Cookie HBCPSID傳遞； -
token || admintoken：用戶登錄授權(quán)或管理員登錄授權(quán)都可以；
圖片 -
sign：需要簽名，一般用于服務(wù)端相互調(diào)用，詳見(jiàn) API HMAC-SHA1簽名。
-
- 接口權(quán)限，定義在
-
@apiDescription- 盡可能詳細(xì)說(shuō)明接口的用途及相關(guān)邏輯，如
@apiDescription 使用手機(jī)號(hào)找回密碼的第一步，調(diào)用該接口先驗(yàn)證用戶輸入的手機(jī)號(hào)是否已經(jīng)綁定某個(gè)帳號(hào)，未綁定給出提示，已經(jīng)綁定則發(fā)送驗(yàn)證碼、重置密碼。
- 盡可能詳細(xì)說(shuō)明接口的用途及相關(guān)邏輯，如
-
@apiParam- 準(zhǔn)確定義數(shù)據(jù)類型；
- 準(zhǔn)確定義取值范圍，如
{String{1..32}}、{String{YYYY-mm-dd}}、{String="0","1"}； - 準(zhǔn)確定義是否是可選參數(shù)，可選參數(shù)帶
[]，如@apiParam {String} [stage]；
-
@apiError- 公共錯(cuò)誤，直接使用
apidoc/common.php中定義的錯(cuò)誤，如@apiUse InvalidToken； -
NotFound和ValidationError不允許使用公共定義錯(cuò)誤（即不可使用@apiUse），需要準(zhǔn)確定義具體錯(cuò)誤，如:
圖片
- 公共錯(cuò)誤，直接使用
-
@apiSampleRequest- GET接口：不寫(xiě)，默認(rèn)使用
apidoc.json的sampleUrl自動(dòng)組裝請(qǐng)求地址 - 其他接口：
@apiSampleRequest off，我們用Postman
- GET接口：不寫(xiě)，默認(rèn)使用
接口分組
- 一般按功能模塊分組，一個(gè)分組對(duì)應(yīng)一個(gè)或多個(gè)php文件，每個(gè)php文件只對(duì)應(yīng)一個(gè)分組；
- 所有權(quán)限為
admintoken的接口（不包括權(quán)限為token || admintoken的接口），放在該接口模塊的管理中心接口分組，admin.php文件中； - 所有權(quán)限為
sign的接口（短信模塊除外），放在該接口模塊的內(nèi)部服務(wù)接口分組，internal.php文件中；
接口版本管理
同一個(gè)大版本下，只有當(dāng)你的接口變更會(huì)影響到調(diào)用者時(shí)，才需要升級(jí)minor版本（如果被修改的版本還沒(méi)有調(diào)用者，自然無(wú)需升級(jí)版本），如從1.0.0升至1.1.0。
-
升級(jí)版本時(shí)，需要將舊的apidoc注釋拷貝至
apidoc/history.php，并升級(jí)apiVersion
圖片 升級(jí)接口大版本時(shí)，拷貝舊版本文件目錄作為新版本并升級(jí)接口版本（如拷貝v1，重命名為v2，修改新版本中所有接口為
2.0.0版本）。-
調(diào)用者在查看文檔時(shí)，通過(guò)版本比較，可以輕易知曉新版本做了哪些變更。
圖片
圖片 -
過(guò)期的接口，標(biāo)記
@apiDeprecated，說(shuō)明應(yīng)該使用哪些接口替代：-
在過(guò)期接口apidoc注釋前增加：
圖片 -
文檔顯示：
圖片
-
文檔生成
-
DEVQA服務(wù)器配置了定時(shí)任務(wù)(
crontab -l查看)，每隔1分鐘重新生成文檔。
圖片 -
新建接口模塊時(shí)，
- 需要修改定時(shí)任務(wù)
crontab -e； - 在apidoc模板中新增導(dǎo)航
vim /usr/lib/node_modules/apidoc/template/index.html；
圖片
- 需要修改定時(shí)任務(wù)
api測(cè)試注意要點(diǎn)
- 是否嚴(yán)格遵循本規(guī)范定義接口；
- 錯(cuò)誤處理周全，不遺漏任何的錯(cuò)誤，錯(cuò)誤的message必須簡(jiǎn)潔明了并給予指引，如“開(kāi)團(tuán)時(shí)間為1-5天，請(qǐng)重新輸入”；
- 接口權(quán)限控制是否OK，是否存在安全隱患；
- 接口文檔和實(shí)現(xiàn)是否完全一致；
-請(qǐng)求參數(shù)的名稱、類型、是否可選、描述都必須準(zhǔn)確和見(jiàn)名知意； - 返回參數(shù)的名稱、類型、描述都必須準(zhǔn)確詳盡。
