---
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` 确认动态文档包含新路径