leebai / hyperf-esaydoc
this is hyperf annotation document generate package
Requires
This package is not auto-updated.
Last update: 2025-04-27 20:12:53 UTC
README
Documentation
doc地址:https://gitee.com/bai8li/esay-doc
EsayDoc文档使用
1.生成api接口文档列表，和服务文档列表
2.配合mzh/validate 验证器可自动根据验证规则、场景生成文档所需参数
3.无需手动编写doc文档一键生成导出postman,eolinker等文档
1.开始使用
安装文档
composer require leebai/hyperf-esaydoc
发布配置文件
php bin/hyperf.php vendor:publish leebai/hyperf-esaydoc
默开启文档web访问，如需关闭，在 config/autoload/doc.php 将enable设为false
2.主要注解说明
Api :标注api接口说明
Service :服务接口
Responses :返回参数
Params :入参属性,输出字段
3.访问生成的文档
访问 http://youdDomain/doc
4文档详情概述
所有配置请到config/autoload/doc.php修改，已标注好
4.1 api列表功能
1.自动生成登录配置，即可以保存token到postman模拟登录的真实场景
2.自动根据接口是否需要登录添加token到header头进行鉴权
3.根据是否是列表自动添加currantPage(当前页),row(每页条数)
4.自动根据请求方法生成query，或者form-data 参数体，并根据默认值填入对应的值，可直接进行请求
4.2 服务列表功能
1.生成服务对应的入参，返回值列表对应的参数
2.根据是否是列表自动添加currantPage(当前页),row(每页条数)
5注解参数详解
...
/**
* @AutoController
* @Api(name="测试管理" ,needLogin=false)
*/
class TestController
{
/**
*
* @ApiOperation(name="测试登录",d›esc="这是一个测试登录的接口",needLogin=true,method="GET")
* @Params(type="1" ,params={
* @Param(name="userName",type="string",desc="用户名",required=true,default="254497767"),
* })
* @Responses(isList=false,data={
* @Param(name="userName",type="string",desc="用户名",required=true,default="254497767")},
* failStatus={@FailResponse(status="2",message="普通错误")})
*/
public function index()
{
...
| Api | 标注在类上面 | 描述该类是属于什么模块 |
|---|---|---|
| name | 如:用户模块,商品模块 | 描述该模块功能的名字 |
| needLogin | true/false | 描述该模块是否需要登录 |
示例: @Api(name="测试管理" ,needLogin=false)
| ApiOperation | 标注在方法上 | 描述方法具体操作 |
|---|---|---|
| name | 如:登录，注册 | 描述该接口功能的名字 |
| desc | 如:后台管理员登录，新用户前台注册 | 描述该接口功能的详情描述 |
| method | GET/POST/PUT/DELETE | 描述该模块请求方法,如与hyperf冲突，hyperf优先 |
| needLogin | true/false | 描述该接口是否需要登录,与Api冲突,此处优先 |
示例: @ApiOperation(name="测试登录",d›esc="这是一个测试登录的接口",needLogin=true,method="GET")
| Service | 标注在类上面 | 描述该接口是属于什么服务模块 |
|---|---|---|
| name | 如:用户模块服务,商品模块服务 | 描述该服务模块功能的名字 |
` |
示例: @Service(name="用户服务模块")
---
ServiceOpeation|标注在服务接口的方法上|描述方法具体操作
---|--|---
name| 如:添加用户，编辑用户信息 |该服务接口的名字
desc| 如:后台管理员添加用户，后台编辑用户信息 |服务接口的详情描述
示例: @ServiceOpeation(name="添加用户",desc="添加管理员用户")
---
Params|标注在方法上|描述该方法参数体
---|--|---
type| 请求参数(0,默认)/响应参数(1)/header头(2) |描述该参数体的类型
params| |所有参数Param的数组集合
示例: @Params(params={
* @Param(name="userName",type="string",desc="用户名",required=true,default="254497767"),
* })
---
Param|标注在Params内部|具体的参数内心
---|--|---
name| 如:username,email,passworld |请求的参数名
required| true/false |该参数是否为必填
default| 如:john john@mallae.com 123456 |该参数的默认值
type| string/number/file |该参数类型
desc| 如:用户名，邮箱，密码| 该参数的具体描述
示例: @Param(name="userName",type="string",desc="用户名",required=true,default="254497767"),
---
Responses|标注在方法上|描述该方法或者服务的返回参数
---|--|---
status| 返回对应的状态码，如:0,100,400 |成功返回状态码(配置文件配置)
message| 如:ok |成功返回消息
isList| true/false | 返回的是否是列表,生成对应的page信息
data| |所有响应Param的数组集合
failStatus|如:{status:302,message:请先登录},{status:300,message:权限不足} |错误状态列表
示例: * @Responses(isList=false,data={
* @Param(name="userName",type="string",desc="用户名",required=true,default="254497767"),
* failStatus={
* @FailResponse(status="2",message="普通错误"),
* @FailResponse(status="3",message="不是普通错误"),
* }
* )
---
FailResponse|标注Responses内部的failStatus里|可多个，描述对应的错误状态
---|--|---
status| 如:300，302 |状态码
message| 如:请先登录，权限加班 |错误消息
示例: @FailResponse(status="2",message="普通错误"),
#### 实际使用截图
**接口配置**
**postman示例**
