## 編寫注釋 由于API接口文檔根據解析代碼中的注釋生成，需按照一定的書寫規則來生成 ## 書寫規范 書寫參數時有如下幾個規范 * 每個參數書寫在一行 * 每個參數以 @+參數名，用空格 與參數值隔開 如 \* @參數名 參數值 * 參數值與數據表字段注釋的內容，避免出現 空格 或 : (冒號) ## 參數說明 | 參數名 | 參數值 | 說明 | 書寫規范 | | --- | --- | --- | --- | | title | | 接口名稱 | 任意字符 | | desc | | 接口說明 | 任意字符 | | author | | 作者 | 任意字符 | | url | | 真實的接口URL | 任意字符 | | method | `GET``POST``PUT``DELETE` | 請求類型 | | | tag | | 接口Tag標簽 | 多個標簽用 空格隔開 | | header | 請求頭Headers參數 | 可定義多個，每個一行，每個屬性用空格隔開 | | param | 請求參數 | 可定義多個，每個一行，每個屬性用空格隔開 | | return | 響應結果 | 可定義多個，每個一行，每個屬性用空格隔開 | ## header 的參數 | 參數名 | 說明 | 書寫規范 | | --- | --- | --- | | name | 參數的字段名 | 如：name:Authorization | | require | 是否必填 | 如：require:1 為必填 | | default | 默認值 | 如：default:123 | | desc | 字段說明 | | ## param、return 的參數 | 參數名 | 說明 | 書寫規范 | | --- | --- | --- | | name | 參數的字段名 | 如：name:username，如直接使用ref引入某個定義，可不配置name | | type | 字段類型 | `int``string``boolean``object``array``tree` | | require | 是否必填 | 如：require:1 為必填 | | default | 默認值 | 如：default:123 | | desc | 字段說明 | | | ref | 引入定義的路徑，可引入全局定義、服務層方法類、模型方法 | 如：ref:definitions\\pagingParam或：ref:app\\services\\ApiDocTest\\get 或：ref:app\\model\\Apps\\getList | | field | 當ref配置為引入模型字段時，用field來指定引入的字段 | 如：field:id,username,nickname ；則只會引入模型的 id,username,nickname字段 | | withoutField | 當ref配置為引入模型字段時，用withoutField來指定過濾掉的字段 | 如：withoutField:id,username,nickname；則引入模型除 id,username,nickname字段外的所有字段 | | params | 字段類型為`object`或`array`，給其定義子節點參數 | 如：params:id int 1 唯一id,name:string 0 姓名 | | childrenField | 字段類型為`tree`時，給其定義子節點字段名 | 默認為 children | | childrenDesc | 字段類型為`tree`時，給其定義子節點字段名的備注 | | ## 控制器注釋 1、接口文檔將按照在配置文件`/config/apidoc.php`中配置的 controllers 控制器列表，來生成. 若你希望 某個控制器被解析，那么首先在配置項中加入該控制器，如下： ~~~ // config/apidoc.php // 將 app\controller\ApiDocTest.php 控制器加入配置 'controllers' => [ 'controller\\ApiDocTest', ], ~~~ 2、為控制器加上一些注釋，以讓文檔可讀性更高（當然這不是必須的） ~~~ <?php namespace app\controller; /** * @title Api接口文檔測試 * @controller ApiDocTest */ class ApiDocTest { //... } ~~~ ## 控制器注釋參數 | 參數名 | 參數值 | 說明 | | --- | --- | --- | | title | | 控制器名稱 | | controller | | 控制器 | | group | 定義在配置文件 groups 中分組的name | 所屬分組 | 此時刷新文檔頁面，得到一個控制器被解析  ## 接口注釋 控制器中的每一個符合注釋規則的方法都會被解析成一個API接口 ## 基礎注釋 先來體驗一個最基本的注釋，所得到的結果 我們在控制器中加入如下方法，如下 ~~~ <?php namespace app\controller; /** * @title Api接口文檔測試 * @controller ApiDocTest */ class ApiDocTest { /** * @title 基礎的注釋方法 * @desc 最基礎的接口注釋寫法 * @author HG * @url /apidocTest/base * @method GET * @tag 測試 基礎 * @header name:Authorization require:1 desc:Token * @param name:username type:string require:1 desc:用戶名 * @param name:password type:string require:1 desc:登錄密碼MD5 * @param name:phone type:string require:1 desc:手機號 * @param name:sex type:int require:0 default:0 desc:性別 * @return name:id type:int desc:新增用戶的id */ public function test(){ return json(["id"=>1]); } } ~~~ 以上注釋，我們得到的效果如下  ## 通用注釋 通過定義通用的公共注釋參數來實現 可復用性，避免每個接口都定義一大堆同樣的參數 ## 1、增加配置 首先，在配置文件 config/apidoc.php 配置文件中，指定一個控制器為定義公共注釋的控制器 ~~~ // config/apidoc.php // 指定公共注釋定義的文件地址 'definitions'=>"app\controller\Definitions", ~~~ ## 2、定義通用注釋 添加一些通用的方法及注釋，（定義param 與return 參數與定義接口書寫規則一致） ~~~ <?php namespace app\controller; class Definitions { /** * @title 獲取分頁數據列表的參數 * @param name:pageIndex type:int require:0 default:0 desc:查詢頁數 * @param name:pageSize type:int require:0 default:20 desc:查詢條數 */ public function pagingParam(){} /** * @title 返回字典數據 * @return name:id type:int desc:唯一id * @return name:name type:string desc:字典名 * @return name:value type:string desc:字典值 */ public function dictionary(){} } ~~~ ## 3、使用定義 在接口注釋中的 param 與 retrun 可通過 ref:definitions\\XXX 來指定引入的 通用注釋 ~~~ <?php namespace app\controller; class ApiDocTest { /** * @title 引入定義注釋 * @desc 引入通用注釋所定義的通用參數 * @author HG * @url /apidocTest/definitions * @method POST * @param name:page type:object ref:definitions\pagingParam desc:分頁參數 * @param ref:definitions\pagingParam * @return name:list type:array ref:definitions\dictionary */ public function definitions(){ //... } } ~~~ 以上param用了兩種方式引入，分別是參數指定 字段名 name與 type ，與不指定字段名 * 指定字段名：會將引入的參數在該字段屬性下，如下效果 * 不指定字段名：直接引入所有參數 效果如下  ## 邏輯層注釋 在實際開發中，控制器只對參數做基礎校驗等處理，實際的業務邏輯處理通常會分層給邏輯層來處理（我這里把業務邏輯層叫service，您也可以根據自己開發來定義 業務邏輯層），我們可直接引入業務邏輯層的注釋來實現接口參數的定義 ## 增加業務邏輯層 1、在項目 app 目錄下新建 service 文件夾（您也可以叫別的） 2、在此文件夾下新建一個ApiDoc.php文件，內容如下： ~~~ <?php namespace app\services; class ApiDoc { /** * @title 返回會員信息 * @param name:id type:int require:1 desc:唯一id * @return name:id type:int desc:唯一id * @return name:name type:string desc:姓名 * @return name:phone type:string desc:電話 */ public function getUserInfo(){} } ~~~ ## 引用邏輯層注釋 在控制器的接口注釋中的 param 與 retrun 可通過 ref:app\\services\\ApiDoc\\getUserInfo來指定引入邏輯層的注釋 ~~~ <?php namespace app\controller; class ApiDocTest { /** * @title 引入邏輯層注釋 * @desc 引入業務邏輯層的注釋參數 * @author HG * @url /apidocTest/service * @method GET * @param ref:app\services\ApiDoc\getUserInfo * @return name:userInfo type:object ref:app\services\ApiDoc\getUserInfo */ public function service(){ //... } } ~~~ 效果如下  ## 模型注釋 接口參數都與數據表息息相關，很多接口參數均由數據表字段而來。我們可以直接引入指定模型的數據表字段來生成參數說明，省去了一大堆接口注釋與維護工作。 ## 給數據表字段添加注釋 建議為數據表字段添加注釋，即讓數據表字段可讀性更高，也讓文檔可讀性更高。 我們直接在數據表給相應字段添加注釋，如下SQL供參考 ~~~ CREATE TABLE `user` (? `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '用戶id', `username` varchar(64) NOT NULL COMMENT '用戶名', `nickname` varchar(64) DEFAULT NULL COMMENT '昵稱', `password` char(64) NOT NULL COMMENT '登錄密碼', `avatar` varchar(255) DEFAULT NULL COMMENT '頭像', `regip` bigint(11) DEFAULT NULL COMMENT '注冊IP', `update_time` int(11) unsigned DEFAULT NULL COMMENT '更新時間', `state` tinyint(1) DEFAULT '1' COMMENT '狀態', `phone` char(32) DEFAULT NULL COMMENT '聯系電話', `create_time` int(10) DEFAULT NULL COMMENT '創建時間', `sex` tinyint(1) unsigned DEFAULT '1' COMMENT '性別', `delete_time` int(10) DEFAULT NULL COMMENT '刪除時間', `role` varchar(64) DEFAULT NULL COMMENT '角色', `name` varchar(64) DEFAULT NULL COMMENT '姓名', PRIMARY KEY (`id`)?) ENGINE=MyISAM AUTO_INCREMENT=23 DEFAULT CHARSET=utf8" ~~~ ## 模型方法的注釋 可為引入的數據模型方法添加相應注釋來實現 field（返回指定字段）、withoutField（排除指定字段）、addField（添加指定字段） | 參數 | 說明 | 書寫規范 | | --- | --- | --- | | field | 返回指定字段 | 英文格式逗號 , 分開指定的字段 | | withoutField | 排除指定字段 | 英文格式逗號 , 分開指定的字段 | | addField | 添加指定字段 | 可定義多個，每行為一個參數 | | |— name | 參數的字段名 | 如：name:group\_name | | |— type | 字段類型 | int | string | ... 等 | | |— default | 默認值 | 如：default:1 | | |— desc | 字段說明文字 | | ~~~ <?php namespace app\model; class User extends BaseModel { /** * @title 根據id獲取明細 * @field id,username,nickname,state,sex * @addField name:group_name type:string desc:會員組名稱 * @addField name:role_name type:string desc:角色名稱 */ public function getInfo($id){ $res = $this->get($id); return $res; } } ~~~ ## 控制器引用模型注釋 ~~~ <?php namespace app\controller; class ApiDocTest { /** * @title 引用模型注釋 * @desc param參數為直接引用模型參數，return則是引用邏輯層，通過邏輯層引用模型參數 * @author HG * @url /apidocTest/model * @method GET * @param ref:app\model\User\getInfo * @return name:users type:array ref:app\services\ApiDoc\getUserList */ public function model(){ //... } } ~~~