Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ composer analyse # PHPStan 静态分析(-l 0,仅 src/)
composer cs-fix # php-cs-fixer 格式化 src 和 tests
```

CI 矩阵为 PHP 8.2/8.3/8.4 + Hyperf 3.2(pin `hyperf/di:3.2.*` + `tangwei/dto:dev-master`)。本包通过 `tangwei/dto ~3.2` 传递依赖 Hyperf ~3.2,不兼容 Hyperf 3.1。
CI 矩阵覆盖 PHP 8.1/8.2/8.3/8.4 + Hyperf 3.1,以及 PHP 8.2/8.3/8.4 + Hyperf 3.2(pin 对应 `hyperf/di` + `tangwei/dto:dev-master`)。本包通过 `tangwei/dto ~4.0.0` 传递依赖 Hyperf 3.1/3.2。

## 架构核心

Expand Down
10 changes: 7 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
[![Latest Stable Version](https://img.shields.io/packagist/v/tangwei/apidocs)](https://packagist.org/packages/tangwei/apidocs)
[![Total Downloads](https://img.shields.io/packagist/dt/tangwei/apidocs)](https://packagist.org/packages/tangwei/apidocs)
[![License](https://img.shields.io/packagist/l/tangwei/apidocs)](https://github.com/tw2066/api-docs)
[![PHP Version](https://img.shields.io/badge/php-%3E%3D8.2-blue)](https://www.php.net)
[![PHP Version](https://img.shields.io/badge/php-%3E%3D8.1-blue)](https://www.php.net)

[English](./README_EN.md) | 中文

Expand All @@ -22,14 +22,18 @@

## 📋 环境要求

- PHP >= 8.2
- Hyperf ~3.2
- PHP >= 8.1
- Hyperf ~3.1 或 ~3.2
- DTO ~4.0.0
- Swoole >= 5.0 或 Swow

## 💡 使用须知

- 控制器方法尽可能返回具体的类(包含简单类型),这样能更好地生成文档
- 当返回类无法满足需求时,可使用 `#[ApiResponse]` 注解补充
- DTO 4.0 输入只接受字段 primaryKey:有 `#[JSONField]` 时使用其外部别名,否则使用 PHP 属性名;private/protected 属性需要正常业务 setter 才能接收输入,readonly/static 属性不参与输入映射。带 `#[Required]` 的字段例外:验证先于映射执行,文档仍将其列为请求必填字段
- 接口属性建议通过 DTO `classMap` 指定具体类;未指定或运行时动态映射时,文档降级为通用 `object`
- 升级到 DTO 4.0 后,建议清理并重新生成 `runtime/container/proxy/` 中的代理文件

## 📦 安装

Expand Down
10 changes: 7 additions & 3 deletions README_EN.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
[![Latest Stable Version](https://img.shields.io/packagist/v/tangwei/apidocs)](https://packagist.org/packages/tangwei/apidocs)
[![Total Downloads](https://img.shields.io/packagist/dt/tangwei/apidocs)](https://packagist.org/packages/tangwei/apidocs)
[![License](https://img.shields.io/packagist/l/tangwei/apidocs)](https://github.com/tw2066/api-docs)
[![PHP Version](https://img.shields.io/badge/php-%3E%3D8.2-blue)](https://www.php.net)
[![PHP Version](https://img.shields.io/badge/php-%3E%3D8.1-blue)](https://www.php.net)

English | [中文](./README.md)

Expand All @@ -22,15 +22,19 @@ Automatic Swagger/OpenAPI documentation generator for the [Hyperf](https://githu

## 📋 Requirements

- PHP >= 8.2
- Hyperf ~3.2
- PHP >= 8.1
- Hyperf ~3.1 or ~3.2
- DTO ~4.0.0
- Swoole >= 5.0 or Swow

## 💡 Important Notes

- Union types are not supported for parameter mapping to PHP classes
- Controller methods should return specific types (including simple types) for better documentation generation
- Use `#[ApiResponse]` annotation when return types cannot fully express the response structure
- DTO 4.0 input uses each field's primaryKey: the external alias when `#[JSONField]` is present, otherwise the PHP property name; private/protected properties require a regular business setter, while readonly/static properties are excluded from input mapping. Fields marked `#[Required]` are the exception: validation runs before mapping, so they remain required request fields in the documentation
- For interface properties, configure a concrete class through the DTO `classMap`; unresolved or runtime-dynamic mappings fall back to a generic `object` schema
- After upgrading to DTO 4.0, clear and regenerate the proxy files in `runtime/container/proxy/`

## 📦 Installation

Expand Down
144 changes: 55 additions & 89 deletions example/Controller/DemoController.php
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,12 @@

namespace HyperfExample\ApiDocs\Controller;

use App\Annotation\TestAnnotation;
use App\DTO\Response\DemoResponse;
use App\DTO\User;
use App\Model\Activity;
use App\Service\GoodsInfoService;
use Hyperf\ApiDocs\Annotation\Api;
use Hyperf\ApiDocs\Annotation\ApiFormData;
use Hyperf\ApiDocs\Annotation\ApiHeader;
use Hyperf\ApiDocs\Annotation\ApiOperation;
use Hyperf\ApiDocs\Annotation\ApiResponse;
use Hyperf\ApiDocs\Annotation\ApiSecurity;
use Hyperf\Database\Model\Relations\HasOne;
use Hyperf\DTO\Annotation\Contracts\RequestBody;
use Hyperf\DTO\Annotation\Contracts\RequestFormData;
use Hyperf\DTO\Annotation\Contracts\RequestHeader;
Expand All @@ -28,9 +22,7 @@
use Hyperf\HttpServer\Annotation\PatchMapping;
use Hyperf\HttpServer\Annotation\PostMapping;
use Hyperf\HttpServer\Annotation\PutMapping;
use Hyperf\HttpServer\Contract\RequestInterface;
use HyperfExample\ApiDocs\DTO\Address;
use HyperfExample\ApiDocs\DTO\Address_1;
use HyperfExample\ApiDocs\DTO\DataType;
use HyperfExample\ApiDocs\DTO\Header\DemoToken;
use HyperfExample\ApiDocs\DTO\PageQuery;
Expand All @@ -43,195 +35,169 @@
use HyperfExample\ApiDocs\DTO\Response\CodeResponse;
use HyperfExample\ApiDocs\DTO\Response\Contact;
use HyperfExample\ApiDocs\DTO\Response\Page;
use HyperfExample\ApiDocs\DTO\Response\ReadonlyResponse;

#[Controller(prefix: '/exampleDemo')]
#[Api(tags: 'demo管理', position: 1)]
#[ApiHeader('apiHeader')]
#[ApiHeader(name: 'apiHeader')]
class DemoController
{
public int $a = 1;

public array $a2 = [];

public function __construct(protected RequestInterface $request)
{
}

#[ApiOperation(summary: '查询测试')]
#[GetMapping(path: 'api')]
public function api(#[RequestQuery] #[Valid] DemoQuery $request): DataType
#[GetMapping(path: 'detail')]
public function detail(#[RequestQuery] #[Valid] DemoQuery $request): DataType
{
dump($request);
return new DataType();
}

/**
* @param DemoQuery[] $request
*/
#[ApiOperation(summary: '查询测试POST Arr')]
#[PostMapping(path: 'apiArr')]
public function apiArr(#[RequestBody] #[Valid] array $request, Address $address): array
#[PostMapping(path: 'list')]
public function list(#[RequestBody] #[Valid] array $request): array
{
dump($request);
return $request;
}

#[ApiOperation(summary: '查询测试POST')]
#[PostMapping(path: 'api')]
#[PostMapping(path: 'create')]
#[ApiHeader(name: 'test', required: true, type: 'string')]
// #[ApiFormData(name: 'photo', required: true, format: 'binary')]
public function apiPost(#[RequestBody] #[Valid] DemoQuery $request): DemoQuery
public function create(#[RequestBody] #[Valid] DemoQuery $request): DemoQuery
{
dump($request);
return $request;
}

#[ApiOperation('1:查询')]
#[PostMapping(path: 'query')]
public function query(#[RequestBody] #[Valid] DemoQuery $request): Contact
#[ApiOperation(summary: '1:查询')]
#[PostMapping(path: 'search')]
public function search(#[RequestBody] #[Valid] DemoQuery $request): Contact
{
dump($request);
return new Contact();
}

#[ApiOperation('2:提交body数据和get参数')]
#[PutMapping(path: 'add')]
public function add(#[RequestBody] #[Valid] DemoBodyRequest $request, #[RequestQuery] DemoQuery $query): ActivityResponse
#[ApiOperation(summary: '2:提交body数据和get参数')]
#[PutMapping(path: 'save')]
public function save(#[RequestBody] #[Valid] DemoBodyRequest $request, #[RequestQuery] DemoQuery $query): ActivityResponse
{
dump($request);
dump($query);
return new ActivityResponse();
}

/**
* @param DemoFormData $formData
* @return Address[]
*/
#[ApiOperation('3:表单提交')]
#[PostMapping(path: 'fromData')]
#[ApiOperation(summary: '3:表单提交')]
#[PostMapping(path: 'formData')]
#[ApiFormData(name: 'photo', format: 'binary')]
// #[ApiResponse(new CodeResponse(new GoodsInfoService()))]
// #[TestAnnotation(new GoodsInfoService())]
// #[ApiResponse(new GoodsInfoService())]
public function fromData(#[RequestFormData] DemoFormData $formData): array
{
$file = $this->request->file('photo');
dump($file);
var_dump($formData);
public function formData(#[RequestFormData] DemoFormData $formData): array
{
return [new Address()];
}

#[ApiOperation('4:查询单条记录')]
#[GetMapping(path: 'find/{id}/and/{in}')]
#[ApiHeader('test2')]
#[ApiOperation(summary: '4:查询单条记录')]
#[GetMapping(path: 'find/{id}/rate/{rate}')]
#[ApiHeader(name: 'test2')]
#[ApiResponse([PhpType::BOOL])]
#[ApiResponse(Address::class, 201)]
#[ApiResponse(Address_1::class, 202)]
#[ApiResponse([Address::class], 203)]
#[ApiResponse([PhpType::INT], 204)]
#[ApiResponse(new Page([Address::class]), 206)]
public function find666666666(int $id, float $in)
public function find(int $id, float $rate): array
{
return ['$id' => $id, '$in' => $in];
return ['id' => $id, 'rate' => $rate];
}

#[ApiOperation('5:分页')]
#[ApiOperation(summary: '5:分页')]
#[GetMapping(path: 'page')]
#[ApiResponse(new Page([new ActivityResponse()]))]
public function page(#[RequestQuery] PageQuery $pageQuery): Page
{
$activitys = Activity::with(['activityUser' => function ($query) {
/* @var HasOne $query */
$query->orderBy('id', 'desc')->with(['case']);
}])
->paginate($pageQuery->getSize());
$arr = [];
foreach ($activitys as $activity) {
$arr[] = ActivityResponse::from($activity);
}
dump(new ActivityResponse());
return new Page($arr, $activitys->total());
$activity = new ActivityResponse();
$activity->id = '1';
$activity->activityName = '示例活动';

return new Page([$activity], 1);
}

#[ApiOperation('6:更新')]
#[ApiOperation(summary: '6:更新')]
#[PutMapping(path: 'update/{id}')]
public function update(int $id): int
{
return $id;
}

#[ApiOperation('7:删除')]
#[ApiOperation(summary: '7:删除')]
#[DeleteMapping(path: 'delete/{id}')]
public function delete(int $id): bool
{
return true;
}

#[ApiOperation('patch方法')]
#[ApiOperation(summary: 'patch方法')]
#[PatchMapping(path: 'patch/{id}')]
public function patch(int $id): int
{
return $id;
}

#[ApiOperation('获取请求头')]
#[PostMapping(path: 'getHeader/{id}')]
#[ApiOperation(summary: '获取请求头')]
#[PostMapping(path: 'header/{id}')]
#[ApiSecurity]
public function getHeader(#[RequestHeader] #[Valid] DemoToken $header)
{
dump($header);
return null;
}
public function header(#[RequestHeader] #[Valid] DemoToken $header): void {}

#[ApiOperation('返回 obj(弃用)', deprecated: true)]
#[ApiOperation(summary: '返回 obj(弃用)', deprecated: true)]
#[GetMapping(path: 'obj')]
public function obj(): object
{
return new Address();
}

#[ApiOperation('登录', security: false)]
#[ApiOperation(summary: '登录', security: false)]
#[PostMapping(path: 'login')]
public function login(#[RequestBody] #[Valid] DemoBodyRequest $request): DemoBodyRequest
{
return $request;
}

#[ApiOperation('返回code统一格式:int')]
#[ApiOperation(summary: '返回code统一格式:int')]
#[PostMapping(path: 'codeInt')]
#[ApiResponse(new CodeResponse(PhpType::INT))]
public function codeInt()
public function codeInt(): CodeResponse
{
$data = 1;
return new CodeResponse($data);
return new CodeResponse(1);
}

#[ApiOperation('返回code统一格式:int+数组')]
#[ApiOperation(summary: '返回code统一格式:int+数组')]
#[PostMapping(path: 'codeIntArr')]
#[ApiResponse(new CodeResponse([PhpType::INT], [CityResponse::class]))]
public function codeIntArr(): CodeResponse
{
$data = 1;
$cityResponse = new CityResponse();
$cityResponse->name = '小明';

dump($cityResponse);
return new CodeResponse($data, [$cityResponse]);
return new CodeResponse(1, [$cityResponse]);
}

#[ApiOperation(summary: 'Dto 字段转换')]
#[PostMapping(path: 'city')]
public function city(): CityResponse
{
$city = new CityResponse();
$city->name = 'name2';
$city->bodyName = [1, 2, 3];
dump($city);

return $city;
}
#[PostMapping(path: 'db')]
public function db(#[RequestBody] #[Valid] DemoDatabaseRequest $request): int

#[ApiOperation(summary: '数据库验证')]
#[PostMapping(path: 'validateDatabase')]
public function validateDatabase(#[RequestBody] #[Valid] DemoDatabaseRequest $request): int
{
dump($request);
return 1;
}

#[ApiOperation(summary: '只读响应字段')]
#[GetMapping(path: 'readonly')]
public function readonly(): ReadonlyResponse
{
return new ReadonlyResponse('1', date('Y-m-d H:i:s'));
}
}
29 changes: 0 additions & 29 deletions example/Controller/TestController.php

This file was deleted.

Loading
Loading