基于 Hyperf 框架的 swagger 文档生成组件，支持swoole/swow驱动
- 声明参数类型完成自动注入，参数映射到PHP类，根据类和注解自动生成Swagger文档
- 代码DTO模式，可维护性好，扩展性好
- 支持数组(类/简单类型)，递归，嵌套
- 支持注解数据校验
- 支持api token
- 支持PHP8原生注解，PHP8.1枚举
- 支持openapi 3.0
- php版本 >= 8.1，参数映射到PHP类不支持联合类型
- 控制器中方法尽可能返回类(包含简单类型)，这样会更好的生成文档
- 当返回类的结果满足不了时,可以使用 #[ApiResponse] 注解
请参考example目录
composer require tangwei/apidocs
默认使用swagger-ui,可使用knife4j-ui(功能更强大)
composer require tangwei/knife4j-ui
php bin/hyperf.php vendor:publish tangwei/apidocsconfig/autoload/api_docs.php
<?php
declare(strict_types=1);
use Hyperf\ApiDocs\DTO\GlobalResponse;
use function Hyperf\Support\env;
return [
/*
|--------------------------------------------------------------------------
| 启动 swagger 服务
|--------------------------------------------------------------------------
|
| false 将不会启动 swagger 服务
|
*/
'enable' => env('APP_ENV') !== 'prod',
/*
|--------------------------------------------------------------------------
| 生成swagger文件格式
|--------------------------------------------------------------------------
|
| 支持json和yaml
|
*/
'format' => 'json',
/*
|--------------------------------------------------------------------------
| 生成swagger文件路径
|--------------------------------------------------------------------------
*/
'output_dir' => BASE_PATH . '/runtime/container',
/*
|--------------------------------------------------------------------------
| 生成代理类路径
|--------------------------------------------------------------------------
*/
'proxy_dir' => BASE_PATH . '/runtime/container/proxy',
/*
|--------------------------------------------------------------------------
| 设置路由前缀
|--------------------------------------------------------------------------
*/
'prefix_url' => env('API_DOCS_PREFIX_URL', '/swagger'),
/*
|--------------------------------------------------------------------------
| 设置swagger资源路径,cdn资源
|--------------------------------------------------------------------------
*/
'prefix_swagger_resources' => 'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.5.0',
/*
|--------------------------------------------------------------------------
| 设置全局返回的代理类
|--------------------------------------------------------------------------
|
| 全局返回 如:[code=>200,data=>null] 格式,设置会后会全局生成对应文档
| 配合ApiVariable注解使用,示例参考GlobalResponse类
| 返回数据格式可以利用AOP统一返回
|
*/
// 'global_return_responses_class' => GlobalResponse::class,
/*
|--------------------------------------------------------------------------
| 替换验证属性
|--------------------------------------------------------------------------
|
| 通过获取注解ApiModelProperty的值,来提供数据验证的提示信息
|
*/
'validation_custom_attributes' => true,
/*
|--------------------------------------------------------------------------
| 设置DTO类默认值等级
|--------------------------------------------------------------------------
|
| 设置:0 默认(不设置默认值)
| 设置:1 简单类型会为设置默认值,复杂类型(带?)会设置null
| - 简单类型默认值: int:0 float:0 string:'' bool:false array:[] mixed:null
| 设置:2 (慎用)包含等级1且复杂类型(联合类型除外)会设置null
|
*/
'dto_default_value_level' => 0,
/*
|--------------------------------------------------------------------------
| 全局responses,映射到ApiResponse注解对象
|--------------------------------------------------------------------------
*/
'responses' => [
['response' => 401, 'description' => 'Unauthorized'],
['response' => 500, 'description' => 'System error'],
],
/*
|--------------------------------------------------------------------------
| swagger 的基础配置
|--------------------------------------------------------------------------
|
| 该属性会映射到OpenAPI对象
|
*/
'swagger' => [
'info' => [
'title' => 'API DOC',
'version' => '0.1',
'description' => 'swagger api desc',
],
'servers' => [
[
'url' => 'http://127.0.0.1:9501',
'description' => 'OpenApi host',
],
],
'components' => [
'securitySchemes' => [
[
'securityScheme' => 'Authorization',
'type' => 'apiKey',
'in' => 'header',
'name' => 'Authorization',
],
],
],
'security' => [
['Authorization' => []],
],
'externalDocs' => [
'description' => 'Find out more about Swagger',
'url' => 'https://github.com/tw2066/api-docs',
],
],
];php bin/hyperf.php start
[INFO] Swagger docs url at http://0.0.0.0:9501/swagger
[INFO] TaskWorker#1 started.
[INFO] Worker#0 started.
[INFO] HTTP Server listening at 0.0.0.0:9501看到
Swagger docs url显示，表示文档生成成功，访问/swagger即可以看到swagger页面 安装knife4j-ui，访问/swagger/doc即可以看到knife4j页面 访问/swagger/redoc，可以看到redoc页面
命名空间:
Hyperf\DTO\Annotation\Contracts
- 获取Body参数
public function add(#[RequestBody] DemoBodyRequest $request){}- 获取GET参数
public function add(#[RequestQuery] DemoQuery $request){}- 获取表单请求
public function fromData(#[RequestFormData] DemoFormData $formData){}- 获取文件(和表单一起使用)
#[ApiFormData(name: 'photo', format: 'binary')]- 获取Body参数和GET参数
public function add(#[RequestBody] DemoBodyRequest $request, #[RequestQuery] DemoQuery $query){}- 优先级: 方法 > 类 > 全局
#[ApiSecurity('Authorization')]
public function getUserInfo(DemoToken $header){}注意: 一个方法，不能同时注入RequestBody和RequestFormData
-
php暂不能定义数组类型，返回的数据类型不能完全满足
当不能满足时，可以通过ApiResponse注解来解决
use Hyperf\ApiDocs\Annotation\ApiResponse; use Hyperf\DTO\Type\PhpType; #[ApiResponse([PhpType::BOOL], 201)] #[ApiResponse([PhpType::INT], 202)] #[ApiResponse([PhpType::FLOAT], 203)] #[ApiResponse([PhpType::ARRAY], 204)] #[ApiResponse([PhpType::OBJECT], 205)] #[ApiResponse([PhpType::STRING], 206)] #[ApiResponse([Address::class], 207)] #[ApiResponse([PhpType::INT], 208)] #[ApiResponse([PhpType::BOOL])] public function test(){}
-
php暂不支持泛型，当返回存在相同结构时候，需要写很多类来返回
例: 分页只有
content结构是可变，可以通过#[ApiVariable]配合使用use Hyperf\ApiDocs\Annotation\ApiVariable; class Page { public int $total; #[ApiVariable] public array $content; public function __construct(array $content, int $total = 0) { $this->content = $content; $this->total = $total; } }
控制器
#[ApiOperation('分页')] #[GetMapping(path: 'activityPage')] #[ApiResponse(new Page([ActivityResponse::class]))] public function activityPage(#[RequestQuery] PageQuery $pageQuery): Page { $activityPage = Activity::paginate($pageQuery->getSize()); $arr = []; foreach ($activityPage as $activity) { $arr[] = ActivityResponse::from($activity); } return new Page($arr, $activityPage->total()); }
通过
#[ApiResponse(new Page([ActivityResponse::class]))]会生成相应的文档
#[Controller(prefix: '/demo')]
#[Api(tags: 'demo管理', position: 1)]
class DemoController extends AbstractController
{
#[ApiOperation(summary: '查询')]
#[PostMapping(path: 'index')]
public function index(#[RequestQuery] #[Valid] DemoQuery $request): Contact
{
$contact = new Contact();
$contact->name = $request->name;
var_dump($request);
return $contact;
}
#[PutMapping(path: 'add')]
#[ApiOperation(summary: '提交body数据和get参数')]
public function add(#[RequestBody] DemoBodyRequest $request, #[RequestQuery] DemoQuery $query)
{
var_dump($query);
return json_encode($request, JSON_UNESCAPED_UNICODE);
}
#[PostMapping(path: 'fromData')]
#[ApiOperation(summary: '表单提交')]
#[ApiFormData(name: 'photo', type: 'file')]
public function fromData(#[RequestFormData] DemoFormData $formData): bool
{
$file = $this->request->file('photo');
var_dump($file);
var_dump($formData);
return true;
}
#[GetMapping(path: 'find/{id}/and/{in}')]
#[ApiOperation('查询单体记录')]
#[ApiHeader(name: 'test')]
public function find(int $id, float $in): array
{
return ['$id' => $id, '$in' => $in];
}
}安装hyperf框架验证器hyperf/validation, 并配置(已安装忽略)
- 注解
RequiredBetweenDateEmailImageIntegerNullableNumericUrlValidation... - 校验生效
只需在控制器方法中加上 #[Valid] 注解
public function index(#[RequestQuery] #[Valid] DemoQuery $request){}
class DemoQuery
{
#[ApiModelProperty('名称')]
#[Required]
#[Max(5)]
#[In(['qq','aa'])]
public string $name;
#[ApiModelProperty('正则')]
#[Str]
#[Regex('/^.+@.+$/i')]
#[StartsWith('aa,bb')]
#[Max(10)]
public string $email;
#[ApiModelProperty('数量')]
#[Required]
#[Integer]
#[Between(1,5)]
public int $num;
}注解的验证支持框架所有验证, 组件提供了常用的注解用于验证
- 使用自定义验证注解, 创建注解类继承
Hyperf\DTO\Annotation\Validation\BaseValidation - 重写
$rule属性或getRule方法
//示例
#[Attribute(Attribute::TARGET_PROPERTY)]
class Image extends BaseValidation
{
protected $rule = 'image';
}- 大家都习惯了框架的
required|date|after:start_date写法
//可以通过Validation实现
#[Validation('required|date|after:start_date')]- 需要支持数组里面是int数据情况
'intArr.*' => 'integer'的情况
//可以通过Validation中customKey来自定义key实现
#[Validation('integer', customKey: 'intArr.*')]
public array $intArr;PHP原生暂不支持
int[]或Class[]类型, 使用示例
/**
* class类型映射数组.
* @var \App\DTO\Address[]
*/
#[ApiModelProperty('地址')]
public array $addressArr;
/**
* 简单类型映射数组.
* @var int[]
*/
#[ApiModelProperty('int类型的数组')]
public array $intArr;
/**
* 通过注解映射数组.
*/
#[ApiModelProperty('string类型的数组')]
#[ArrayType('string')]
public array $stringArr;控制器中使用
AutoController注解,只收集了POST方法
api-docs引入到dto组件
标记为dto类
use Hyperf\DTO\Annotation\Dto;
#[Dto]
class DemoQuery
{
}- 可以设置返回枚举
#[Dto(Convert::SNAKE)], 批量转换下划线返回的key Dto注解不会生成文档, 要生成对应文档使用JSONField注解
用于设置属性的别名
use Hyperf\DTO\Annotation\Dto;
use Hyperf\DTO\Annotation\JSONField;
#[Dto]
class DemoQuery
{
#[ApiModelProperty('这是一个别名')]
#[JSONField('alias_name')]
#[Required]
public string $name;
}- 设置JSONField后会生成代理类,生成
alias_name属性 - 接受和返回字段都以
alias_name为准
RPC 返回PHP对象
aspects.php中配置
return [
\Hyperf\DTO\Aspect\ObjectNormalizerAspect::class
]当框架导入 symfony/serializer (^5.0) 和 symfony/property-access (^5.0) 后，并在 dependencies.php 中配置一下映射关系
use Hyperf\Serializer\SerializerFactory;
use Hyperf\Serializer\Serializer;
return [
Hyperf\Contract\NormalizerInterface::class => new SerializerFactory(Serializer::class),
];# 1.启动生成代理类和注解缓存
php bin/hyperf.php start
# 2.打包
php bin/hyperf.php phar:build
生成类访问器（Getter & Setter）
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent