前言

說明
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 表示輸入，后面是文件夾路徑 <br/>
-o 表示輸出，后面是文件夾路徑 <br/>
默認會帶上-c，在當前路徑下尋找配置文件 apidoc.json，如果找不到則會在package.json中尋找 "apidoc": { } <br/>
-f 為文件過濾，后面是正則表達式，示例為只選著js文件 <br/>
-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命名規范

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.phpapi_up.php...

使用的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). 列表為空也需要返回分頁

總結

以上是生活随笔為你收集整理的php - Api 接口写法规范和要求的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。