使用apiDoc書寫API文件規範

fxm547發表於2018-01-22

API

首發於fxm5547的部落格

詳細閱讀apiDoc官方文件

詳細閱讀官方文件：apidocjs.com

專案中apiDoc檔案結構

整體結構
apidoc.json
common.php
- 公共部分定義-許可權（apiPermission）
  - 定義
  - 使用
- 公共部分定義-狀態碼分組（apiSuccess、apiError）
  - 定義
  - 使用
- 公共部分定義-錯誤響應（apiError、apiErrorExample）
  - 定義
  - 使用
define.php
- 公共部分定義-api分組
- 定義
- 使用

介面具體apidoc定義

介面最新定義在程式碼實現處，歷史版本定義在apidoc/history.php中。
介面定義完整示例：
@apiVersion
目前只用到major和minor，patch始終為0。
@apiName
- 從@api定義轉換而來：如@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
- 介面許可權，定義在apidoc/common.php，許可權分為：
  - none：無需任何授權；
  - token：需要使用者登入授權，可通過header Authorization和Cookie HBSID傳遞；
  - admintoken：需要管理員登入授權，可通過header Authorization和Cookie HBCPSID傳遞；
  - token || admintoken：使用者登入授權或管理員登入授權都可以；
  - sign：需要簽名，一般用於服務端相互呼叫，詳見 API HMAC-SHA1簽名。
@apiDescription
- 儘可能詳細說明介面的用途及相關邏輯，如 @apiDescription 使用手機號找回密碼的第一步，呼叫該介面先驗證使用者輸入的手機號是否已經繫結某個帳號，未繫結給出提示，已經繫結則傳送驗證碼、重置密碼。
@apiParam
- 準確定義資料型別；
- 準確定義取值範圍，如{String{1..32}}、{String{YYYY-mm-dd}}、{String="0","1"}；
- 準確定義是否是可選引數，可選引數帶[]，如@apiParam {String} [stage]；
@apiError
- 公共錯誤，直接使用apidoc/common.php中定義的錯誤，如@apiUse InvalidToken；
- NotFound和ValidationError不允許使用公共定義錯誤（即不可使用@apiUse），需要準確定義具體錯誤，如:
@apiSampleRequest
- GET介面：不寫，預設使用apidoc.json的sampleUrl自動組裝請求地址
- 其他介面：@apiSampleRequest off，我們用Postman

介面分組

一般按功能模組分組，一個分組對應一個或多個php檔案，每個php檔案只對應一個分組；
所有許可權為admintoken的介面（不包括許可權為token || admintoken的介面），放在該介面模組的管理中心介面分組，admin.php檔案中；
所有許可權為sign的介面（簡訊模組除外），放在該介面模組的內部服務介面分組，internal.php檔案中；