初始化本地仓库

2026-08-31 11:33:59 +08:00
commit 663f74b633
2390 changed files with 402918 additions and 0 deletions
@@ -0,0 +1,61 @@
+---
+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` 确认动态文档包含新路径