前言

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

安裝

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

B). 安裝apidoc

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

C). 執(zhí)行生成

# 這個文檔的生成規(guī)則是 # apidoc # -i code_dir # -o output_dir $ apidoc -i myapp/ -o apidoc/ # 對于項目中我們使用 laravel artisan 封裝了一個函數(shù) # 生成 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 文件中.

參數(shù)說明和示例

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

@api {method} path [title]只有使用@api標注的注釋塊才會在解析之后生成文檔，title會被解析為導航菜單(@apiGroup)下的小菜單method可以有空格，如{POST GET}@apiGroup name分組名稱，被解析為導航欄菜單@apiName name接口名稱，在同一個@apiGroup下，名稱相同的@api通過@apiVersion區(qū)分，否者后面@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接口測試地址以供測試，發(fā)送請求時，@api method必須為POST/GET等其中一種@apiDefine name [title] [description]定義一個注釋塊(不包含@api)，配合@apiUse使用可以引入注釋塊在@apiDefine內(nèi)部不可以使用@apiUse @apiUse name引入一個@apiDefine的注釋塊@apiHeader [(group)] [{type}] [field=defaultValue] [description]@apiError [(group)] [{type}] field [description]@apiSuccess [(group)] [{type}] field [description]用法基本類似，分別描述請求參數(shù)、頭部，響應(yīng)錯誤和成功group表示參數(shù)的分組，type表示類型(不能有空格)，入?yún)⒖梢远x默認值(不能有空格)，field上使用[]中擴號表示該參數(shù)是可選參數(shù)@apiParamExample [{type}] [title] example@apiHeaderExample [{type}] [title] example@apiErrorExample [{type}] [title] example@apiSuccessExample [{type}] [title] example用法完全一致，但是type表示的是example的語言類型example書寫成什么樣就會解析成什么樣，所以最好是書寫的時候注意格式化，(許多編輯器都有列模式，可以使用列模式快速對代碼添加*號)

寫法規(guī)范

參數(shù)對齊

/*** @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命名規(guī)范

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

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

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

apiGroup : Home apiName : HomeCheckVerification

返回值約定

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

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

• 返回值中不允許存在 null

返回值對齊

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

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

/*** @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組件

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

• dingo/api 中文文檔

其他說明

A). 接口命名

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

B). 參數(shù)命名

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

C). 路由命名

路由的名稱和坐在分組還有函數(shù)名進行匹配, 使用蛇形寫法 /*** @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). 接口中只能返回有意義的數(shù)據(jù), 對app無用的數(shù)據(jù)不得返回

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

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。