MrleeAdmin/.windsurf/skills/backend-swagger/SKILL.md

name, description, globs

name	description	globs
backend-swagger	Swagger/OpenAPI 注解规范，自动生成 API 文档	app/**/controller/**/*.php app/schema/**/*.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 注解

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