跳至主要內容

接口注解

HG2022年10月25日大约 15 分钟

接口注解

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

基础注释

1、Header参数

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

PHP8原生注解
<?php

use hg\apidoc\annotation as Apidoc;

#[Apidoc\Title("基础示例")]
class ApiDocTest
{ 
    #[
        Apidoc\Title("请求头参数"),
        Apidoc\Method("GET"),
        Apidoc\Header(name:"token",type: "string",require: true,desc: "Token"),
        Apidoc\Query(name:"id",type: "int",require: true,desc: "信息id"),
        Apidoc\Returned("id",type: "int",desc: "信息id"),
    ]
    public function header(){
        //...
    }
}

2、Query参数

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

PHP8原生注解
<?php

use hg\apidoc\annotation as Apidoc;

#[Apidoc\Title("基础示例")]
class ApiDocTest
{ 
    #[
        Apidoc\Title("基础的演示"),
        Apidoc\Method("GET"),
        Apidoc\Query(name:"name",type: "string",require: true,desc: "姓名"),
        Apidoc\Query(name:"phone",type: "string",require: true,desc: "手机号"),
        Apidoc\Returned("id",type: "int",desc: "用户id"),
    ]
    public function query(){
        //...
    }
}

3、Body参数

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

PHP8原生注解
<?php

use hg\apidoc\annotation as Apidoc;

#[Apidoc\Title("基础示例")]
class ApiDocTest
{ 
    #[
        Apidoc\Title("请求Body参数"),
        Apidoc\Method("POST"),
        Apidoc\Param(name:"name",type: "string",require: true,desc: "姓名"),
        Apidoc\Param(name:"phone",type: "string",require: true,desc: "手机号"),
        Apidoc\Returned("id",type: "int",desc: "用户id"),
    ]
    public function body(){
        //...
    }
}

4、路由参数

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

PHP8原生注解
<?php

use hg\apidoc\annotation as Apidoc;

#[Apidoc\Title("基础示例")]
class ApiDocTest
{ 
    #[
        Apidoc\Title("路由参数")
        Apidoc\Method("POST"),
        Apidoc\RouteParam(name:"name",type: "string",require: true,desc: "姓名"),
        Apidoc\RouteParam(name:"phone",type: "string",require: true,desc: "手机号"),
        Apidoc\Returned("id",type: "int",desc: "用户id"),
    ]
    public function route(Request $request,$name,$phone){
        //...
    }
}

5、响应参数

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

PHP8原生注解
<?php

use hg\apidoc\annotation as Apidoc;

#[Apidoc\Title("基础示例")]
class ApiDocTest
{ 
    #[
        Apidoc\Title("响应参数")
        Apidoc\Method("GET"),
        Apidoc\Query(name:"id",type: "int",require: true,desc: "用户id"),
        Apidoc\Returned("id",type: "int",desc: "用户id"),
        Apidoc\Returned("name",type: "string",desc: "姓名"),
        Apidoc\Returned("phone",type: "string",desc: "电话"),
    ]
    public function returned(Request $request,$name,$phone){
        //...
    }
}

通用注解

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

1、增加配置

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

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

2、定义通用注解

添加一些通用的方法及注释，（定义Header、Query、Param 、Returned 参数与接口注释书写规则一致）

PHP8原生注解
<?php
namespace app\controller;

use hg\apidoc\annotation as Apidoc;

class Definitions
{
 
    #[
        Apidoc\Query("pageIndex",type: "int",require: true,default: 1,desc: "查询页数"),
        Apidoc\Query("pageSize",type: "int",require: true,default: 20,desc: "查询条数"),
        Apidoc\Returned("total",type: "int",desc: "总条数"),
    ]
    public function pagingParam(){}
  

    #[
        Apidoc\Returned("id",type: "int",desc: "唯一id"),
        Apidoc\Returned("name",type: "string",desc: "字典名"),
        Apidoc\Returned("value",type: "string",desc: "字典值"),
    ]
    public function dictionary(){}

   
    #[Apidoc\Header("shopid",type: "string",require:true,desc: "店铺id")]
    public function shopHeader(){}
    
}

3、使用定义

在接口注释中的 Header、Query、Param、RouteParam 、Returned 可通过ref引用通用注解：

PHP8原生注解
<?php
namespace app\controller;

use hg\apidoc\annotation as Apidoc;
use app\common\controller\Definitions;

class ApiDocTest
{ 
    #[
        Apidoc\Title("引用公共注解"),
        Apidoc\Method("GET"),
        Apidoc\Header(ref:"shopHeader"),
        Apidoc\Query(ref:[Definitions::class,"pagingParam"] ),
        Apidoc\Returned(ref: [Definitions::class,"pagingParam"]),
        Apidoc\Returned(name: "data",type: "array",ref="dictionary",desc: "字典列表"),
    ]
    public function definitions(){
        //...
    }
}

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

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

逻辑层注解

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

增加业务逻辑层

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

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

PHP8原生注解
<?php
namespace app\services;

use hg\apidoc\annotation as Apidoc;

class ApiDocService
{
    #[
        Apidoc\Param("id",type:"int",require:true,desc="唯一id"),
        Apidoc\Param("sex",type:"int",require:true,desc="性别"),
        Apidoc\Param("age",type:"int",require:true,desc="年龄"),
        Apidoc\Returned("id",type:"int",desc="唯一id"),
        Apidoc\Returned("name",type:"string",desc="姓名"),
        Apidoc\Returned("phone",type:"string",desc="电话"),
    ]
    public function getUserInfo(){}
}

引用逻辑层注解

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

PHP8原生注解
<?php
namespace app\controller;

use hg\apidoc\annotation as Apidoc;
use app\services\ApiDocService;

class ApiDocTest
{ 
    #[
        Apidoc\Title("引入逻辑层注解"),
        Apidoc\Method("POST"),
        Apidoc\Desc("以下Param注解中，三种ref方式等价")
        Apidoc\Param(ref:"app\services\ApiDocService@getUserInfo" ),
        Apidoc\Param(ref:"app\services\ApiDocService\getUserInfo" ),
        Apidoc\Param(ref: [ApiDocService::class,"getUserInfo"] ),
        Apidoc\Returned(ref: [ApiDocService::class,"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 '昵称',
  `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注解来指定表的解析。

PHP8原生注解
<?php
namespace app\controller;

use hg\apidoc\annotation as Apidoc;
use app\services\ApiDocService;

class ApiDocTest
{ 
    #[
        Apidoc\Title("直接引用数据表"),
        Apidoc\Method("POST"),
        Apidoc\Param("userList",type:"array",desc:"用户列表",table:"users" ),
    ]
    public function service(){
       //...
    }
}

模型方法的注解

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

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

use hg\apidoc\annotation as Apidoc;

class User extends BaseModel
{
    #[
        Apidoc\Field(["id","username","nickname","role"]),
        Apidoc\AddField("openid",type:"string",desc:"OpenId"),
        Apidoc\AddField("role",type:"array",desc:"重写role，由于数据表中存在该字段，此处定义会覆盖数据表中的字段",children:[
            ['name'=>'name','type'=>'string','desc'=>'角色名称'],
            ['name'=>'id','type'=>'int','desc'=>'角色id'],
        ]),
    ]
    public function getInfo($id){
        //...
    }
}

引用模型注释

PHP8原生注解
<?php
namespace app\controller;

use hg\apidoc\annotation as Apidoc;
use app\model\User as UserModel;

class ApiDocTest
{ 

    #[
        Apidoc\Title("引入模型注解"),
        Apidoc\Method("POST"),
        Apidoc\Param(ref: "app\model\User@getInfo",desc: "指定引入模型的getInfo方法,会通过getInfo的注解处理数据表字段" ),
        Apidoc\Param(ref: [UserModel::class,"getUserInfo"],desc: "同上" ),
        Apidoc\Param(ref: "app\model\User",desc: "直接引入该模型数据表字段" ),
        Apidoc\Param(ref: UserModel::class,desc: "同上" ),
        Apidoc\Returned(ref:UserModel::class),
    ]
    public function model(){
       //...
    }
}

实体类引用

实体类参数注解

类的属性可使用Property注解

PHP8原生注解
<?php
namespace app\entity;
use hg\apidoc\annotation as Apidoc;
class User
{
    /**
     * 用户id
     * @var int
     */
    public $id;

    /**
     * 用户姓名
     * @var string
     */
    #[Apidoc\Property("name",type: "string",require: true,desc: "用户的姓名")]
    public $name;

    #[Apidoc\Property("arrData",type: "array",require: true,desc: "嵌套数组",children: [
        ['name'=>'id','type'=>'int','require'=>true,'desc'=>'Id'],
        ['name'=>'name','type'=>'string','desc'=>'Name'],
    ])]
    public $arrData;

    #[Apidoc\Property("refData", type: "array", require: true, ref: "app\model\User", desc: "嵌套数组")]
    public $refData;
}

接口引入实体类

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

PHP8原生注解
use hg\apidoc\annotation as Apidoc;
use app\entity\User;
class ApiDocTest
{ 
    #[
        Apidoc\Title("引入实体类"),
        Apidoc\Method("POST"),
        Apidoc\Param(ref: "app\\entity\User",desc: "引入实体类" ),
        Apidoc\Returned("user",type:"array",ref:User::class,desc:"用户信息"),
    ]
    public function refEntity(){
        //...
    }
}

复杂注释

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

PHP8原生注解
<?php
namespace app\controller;

use hg\apidoc\annotation as Apidoc;

class ApiDocTest
{ 
    #[
        Apidoc\Method("POST"),
        Apidoc\Param("info",type:"object",desc="信息",children:[
            ['name'=>'name','type'=>'string','desc'=>'姓名'],
            ['name'=>'sex','type'=>'string','desc'=>'性别'],
            ['name'=>'group','type'=>'object','desc'=>'所属分组','children'=>[
                ['name'=>'group_id','type'=>'int','desc'=>'组id'],
                ['name'=>'group_name','type'=>'string','desc'=>'组名'],
            ]],
        ]),
    ]
    public function test(){
       //...
    }
}

参数说明

参数名参数值说明书写规范
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关闭接口调试
PHP8原生注解
<?php
namespace app\controller;
use hg\apidoc\annotation as Apidoc;

#[Apidoc\NotParse()]
class ApiDocTest
{
    #[Apidoc\NotParse()]
    #[Apidoc\NotResponses()]
    public function model(){
       //...
    }
}
感谢每一位支持的朋友 | 点个Star呗 GitHub
Copyright © 2024 HG