62 lines
1.9 KiB
Markdown
62 lines
1.9 KiB
Markdown
|
---
|
|||
|
|
name: backend-swagger
|
|||
|
|
description: Swagger/OpenAPI 注解规范，自动生成 API 文档
|
|||
|
|
globs:
|
|||
|
|
- "app/**/controller/**/*.php"
|
|||
|
|
- "app/schema/**/*.php"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 注解规范
|
|||
|
|
|
|||
|
|
### 控制器注解
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
use OpenApi\Attributes as OA;
|
|||
|
|
|
|||
|
|
#[OA\Tag(name: '{module_name}管理')]
|
|||
|
|
class {Model}Controller extends Crud
|
|||
|
|
{
|
|||
|
|
#[OA\Get(path: '/{module_route}', summary: '列表', tags: ['{module_name}管理'])]
|
|||
|
|
#[Permission(code: '{module}:{model}:list')]
|
|||
|
|
public function index(Request $request): \support\Response
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Schema 注解
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
#[OA\Schema(title: '创建请求')]
|
|||
|
|
class {Model}CreateRequest
|
|||
|
|
{
|
|||
|
|
#[OA\Property(property: 'name', description: '名称', type: 'string')]
|
|||
|
|
public string $name;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 扫描路径
|
|||
|
|
|
|||
|
|
| 模块 | 路径 |
|
|||
|
|
|------|------|
|
|||
|
|
| AdminAPI 路由分组 | `/adminapi` |
|
|||
|
|
| AdminAPI 注解 path | `/{module_route}`，不要重复写 `/adminapi` |
|
|||
|
|
| API 路由分组 | `/api` |
|
|||
|
|
| API 注解 path | `/{module_route}`，不要重复写 `/api` |
|
|||
|
|
|
|||
|
|
## 文档生成机制
|
|||
|
|
|
|||
|
|
- AdminAPI 动态文档地址：`/adminapi/openapi.json`
|
|||
|
|
- AdminAPI Swagger UI：`/adminapi/openapi`
|
|||
|
|
- API 动态文档地址：`/api/openapi.json`
|
|||
|
|
- API Swagger UI：`/api/openapi`
|
|||
|
|
- 当前项目通过 `app/adminapi/config/route.php` 和 `app/api/config/route.php` 中的 `OpenApiController::document()` 请求时动态扫描生成文档。
|
|||
|
|
- 当前项目尚未内置自动导出 `openapi.json` 到文件系统或 CI 的步骤。
|
|||
|
|
- 路由注册也复用相同扫描源：`RouteRegister::create()->register((new Reader())->getData($config->getScanSources()))`。
|
|||
|
|
|
|||
|
|
## 检查清单
|
|||
|
|
|
|||
|
|
- [ ] 控制器类是否有 `#[OA\Tag]`
|
|||
|
|
- [ ] 每个方法是否有 `#[OA\Get/Post/Put/Delete]`
|
|||
|
|
- [ ] Schema 属性是否有 `#[OA\Property]`
|
|||
|
|
- [ ] 路由已注册 Swagger 扫描路径
|
|||
|
|
- [ ] 后端已重启，确保新控制器被注解路由扫描到
|
|||
|
|
- [ ] 访问 `/adminapi/openapi.json` 或 `/api/openapi.json` 确认动态文档包含新路径
|