## 编写注释 由于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(){ //... } } ~~~