Swagger 接口文档生成

1. 文档生成入口

项目已在 composer.json 配置脚本：

"scripts": {
  "swagger-docs:build": "php vendor/bin/openapi app/common/swagger/OpenApi.php app/admin app/api app/http app/mcp app/platform -o data/openapi.json"
}

2. 操作命令

在根目录执行：

// 生成全部接口文档
composer run swagger-docs:build

// 生成admin模块文档
php vendor/bin/openapi app/common/swagger/OpenApiAdmin.php app/admin -o data/openapi-admin.json

// 生成api模块文档
php vendor/bin/openapi app/common/swagger/OpenApiApi.php app/api -o openapi-api.json

// 生成http模块文档
php vendor/bin/openapi app/common/swagger/OpenApiHttp.php app/http -o data/openapi-http.json

// 生成mcp模块文档
php vendor/bin/openapi app/common/swagger/OpenApiMcp.php app/mcp -o data/openapi-mcp.json

// 生成platform模块文档
php vendor/bin/openapi app/common/swagger/OpenApiPlatform.php app/platform -o data/openapi-platform.json

3. 生成结果

生成文件：

• /data/openapi.json

该文件即 OpenAPI/Swagger 结构化文档，可用于：

• Swagger UI 展示
• 前端联调
• 接口平台导入

4. 在线查看

项目提供页面：

• /public/swagger.html

使用方式：

1. 先在后台管理端登录，浏览器存储token
2. 浏览器打开：域名 + /swagger.html

5. 注解编写位置约定

全局基础信息：

• app/common/swagger/OpenApi.php

业务接口扫描目录：

• app/controller/admin
• app/controller/api
• app/controller/http
• app/controller/mcp
• app/controller/platform

要求：

• 对外可访问的 Controller 接口必须补全 Swagger 注解
• 路由 path、请求方法、参数、响应结构必须与真实接口一致