接口注解

HG大约 15 分钟

接口注解

控制器中的每一个符合注释规则的方法都会被解析成一个API接口

基础注释

1、Header参数

通过Header注解来定义HTTP请求的Header参数

2、Query参数

通过Query注解来定义HTTP请求的Query参数

3、Body参数

通过Param注解来定义HTTP请求的body参数

4、路由参数

通过RouteParam注解来定义请求的路由传参,如url/{name}/{phone},通过以下注解实现

5、响应参数

通过Returned注解来定义HTTP请求响应参数

通用注解

通过定义通用的公共注释参数来实现 可复用性,避免每个接口都定义一大堆同样的参数

1、增加配置

首先在配置文件 apidoc.php 配置文件中,指定一个文件为定义公共注释的类

// apidoc.php
// 指定公共注释定义的文件地址
'definitions'=>"app\controller\Definitions",

2、定义通用注解

添加一些通用的方法及注释,(定义HeaderQueryParamReturned 参数与接口注释书写规则一致)

3、使用定义

在接口注释中的 HeaderQueryParamRouteParamReturned 可通过ref引用通用注解:

以上Returned用了两种方式引入,分别是参数指定 字段名 与 type ,与不指定字段名

  • 指定字段名:会将引入的参数在该字段属性下
  • 不指定字段名:直接引入所有参数

逻辑层注解

在实际开发中,业务逻辑处理通常会分层给逻辑层来处理(我这里把业务逻辑层叫service,你也可以根据自己开发来定义 业务逻辑层),我们可直接引入业务逻辑层的注释来实现接口参数的定义

增加业务逻辑层

1、在项目 app 目录下(或应用/模块目录)新建 services 文件夹(也可以叫别的)

2、在此文件夹下新建一个ApiDoc.php文件,内容如下:

引用逻辑层注解

在控制器的接口注释中的参数可通过 ref="XXX"来指定引入逻辑层的注释

模型注解

接口参数往往与数据表息息相关,很多接口参数均由数据表字段而来。我们可以直接引入指定模型的数据表字段来生成参数说明,省去了一大堆接口注解与维护工作。

给数据表字段添加注释

建议为数据表字段添加注释,即让数据表字段可读性更高,也让文档可读性更高。 我们直接在数据表给相应字段添加注释,如下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 '昵称',
  `avatar` varchar(255) DEFAULT NULL COMMENT '头像',
  `name` varchar(64) DEFAULT NULL COMMENT '姓名',
  `phone` varchar(11) DEFAULT NULL COMMENT '联系电话',
  `role` varchar(255) DEFAULT NULL COMMENT '角色',
PRIMARY KEY (`id`)) ENGINE=MyISAM AUTO_INCREMENT=23 DEFAULT CHARSET=utf8"

直接引用数据表字段

某些表没有模型文件时,可以直接使用table注解来指定表的解析。

模型方法的注解

可为引入的数据模型方法添加相应注释来实现 Field(返回指定字段)、WithoutField(排除指定字段)、AddField(添加指定字段)

参数说明书写规范
Field返回指定字段数组或英文格式逗号 , 分开指定的字段
WithoutField排除指定字段英文格式逗号 , 分开指定的字段
AddField添加指定字段可定义多个,每行为一个参数,也可如下示例嵌套Param使用来定义复杂层级的数据结构
|—参数的字段名如:@Apidoc\AddField("name")
|— type字段类型
|— require是否必填
|— default默认值
|— desc字段说明文字
|— children子参数

引用模型注释

实体类引用

实体类参数注解

类的属性可使用Property注解

接口引入实体类

接口参数Param Query Returned注解中使用ref引入实体类即可。

复杂注释

虽然Apidoc拥有强大的ref引用能力,但某些场景我们需要在一个方法内完成多层数据结构的注解,此时我们可以将HeaderQuery,Param,Returned做嵌套使用即可

参数说明

参数名参数值说明书写规范
Title接口名称任意字符,也可如以下特殊参数直接写在注释前面
Desc接口描述任意字符
MdMarkdown描述,子参数ref引用一个md文件内容Markdown语法字符
Author作者任意字符,默认配置文件的apidoc.default_author
Url真实的接口URL,不配置时会根据控制器目录自动生成任意字符
Method请求类型,默认配置文件的apidoc.default_method,多个类型(数组或用,隔开)GET POST
RouteMiddleware开启自动注册路由时,定义路由中间件
ContentType指定调试时请求ContentType
Tag接口Tag标签多个标签用数组或,(逗号)隔开
Header具体查看 接口参数请求Headers参数可定义多个
Query具体查看 接口参数请求Query参数可定义多个
Param具体查看 接口参数请求Body参数可定义多个
ParamTypejson formdata请求参数类型,默认json
Returned具体查看 接口参数响应结果可定义多个
ResponseSuccess当前接口的成功响应体,通过main=true指定业务数据挂载节点如:
@Apidoc\ResponseSuccess("code",type="int",desc="业务编码")
@Apidoc\ResponseSuccess("data",type="object",desc="业务数据",main=true)
ResponseError当前接口的异常响应体同上
ResponseSuccessMd使用Markdown写成功响应体支持ref引入md文件
ResponseError使用Markdown写异常响应体同上
Before具体查看 功能使用-调试时的事件调试时请求发起前执行的事件可定义多个
After具体查看 功能使用-调试时的事件调试时请求返回后执行的事件可定义多个

接口参数

适用于接口Header,Query,Param,Returned注解

参数名说明书写规范
参数的字段名如:@Apidoc\Param("name"),如使用ref引入某个定义,可不配置参数值
type字段类型string int boolean array object tree file float date time datetime
require是否必填
default默认值
desc字段描述
md引用Markdown描述内容
mdRef引用Markdown描述内容如:/docs/xxx.md
ref引入定义的路径,可引入全局定义、服务层方法类、模型方法
如:@Apidoc\Param(ref="pagingParam")
或:@Apidoc\Param(ref="app\services\ApiDocTest\get")
或:@Apidoc\Param(ref="app\model\User\getList")
mock接口调试时自动生成该字段的值,支持的参数值请查看mock语法
field配置了ref引入时有效,用来指定引入的字段如:field="id,username";则只会引入定义的 id,username字段
withoutField配置了ref引入时有效,用来指定过滤掉的字段如:withoutField:id,username;则引入模型除 id,username字段外的所有字段
childrenField字段类型为tree时,给其定义子节点字段名默认为 children
childrenDesc字段类型为tree时,给其定义子节点字段名的备注
childrenType字段类型为array时,为子参数定义类型,可选值有string int boolean array object
children子参数,多层参数时通过 children 嵌套使用

特殊参数

说明

特殊参数以字符方式直接写到注释中,如下

参数名说明
NotParse不需要解析的方法
NotHeaders不使用配置中的全局请求Headers参数
NotQuerys不使用配置中的全局请求Querys参数
NotParams不使用配置中的全局请求Params参数
NotResponses不使用统一响应体返回数据
NotResponseSuccess不使用成功响应体返回数据
NotResponseError不使用异常响应体返回数据
NotDefaultAuthor不使用默认作者
NotDebug关闭接口调试