{"id":23150872,"url":"https://github.com/hyperf-plus/swagger","last_synced_at":"2025-09-05T20:35:38.083Z","repository":{"id":56987689,"uuid":"297382821","full_name":"hyperf-plus/swagger","owner":"hyperf-plus","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-29T13:36:53.000Z","size":421,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-09T08:51:25.101Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperf-plus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-21T15:31:35.000Z","updated_at":"2024-08-29T10:41:52.000Z","dependencies_parsed_at":"2024-08-29T11:57:30.799Z","dependency_job_id":"d651819b-fed3-4f5e-9c39-c8a051d05ba8","html_url":"https://github.com/hyperf-plus/swagger","commit_stats":{"total_commits":12,"total_committers":1,"mean_commits":12.0,"dds":0.0,"last_synced_commit":"02092fe3c3f4a60208103c243409ad9b82a2251c"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Fswagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Fswagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Fswagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Fswagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperf-plus","download_url":"https://codeload.github.com/hyperf-plus/swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230160255,"owners_count":18182663,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T18:18:48.157Z","updated_at":"2025-08-17T19:32:08.868Z","avatar_url":"https://github.com/hyperf-plus.png","language":"PHP","readme":"# HPlus Swagger - 智能API文档生成组件\n\n[![PHP Version](https://img.shields.io/badge/php-%3E%3D8.0-8892BF.svg)](https://php.net)\n[![Hyperf Version](https://img.shields.io/badge/hyperf-%3E%3D3.0-brightgreen.svg)](https://hyperf.io)\n[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1.1-green.svg)](https://www.openapis.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n一个为 Hyperf 框架打造的智能 API 文档生成组件，支持 OpenAPI 3.1.1 规范，自动集成路由和验证信息，生成美观的交互式文档。\n\n## ✨ 核心特性\n\n- 📝 **自动文档生成** - 基于注解自动生成 OpenAPI 文档\n- 🔄 **智能集成** - 自动识别 Route 和 Validate 组件信息\n- 🎨 **美观界面** - 集成 Swagger UI，支持在线测试\n- 📐 **完整规范** - 支持 OpenAPI 3.1.1 最新规范\n- 🚀 **高性能** - 文档缓存、增量更新\n- 🔧 **灵活配置** - 支持多文档版本、分组管理\n\n## 📦 安装\n\n```bash\ncomposer require hyperf-plus/swagger\n```\n\n### ✅ 兼容性说明\n\n**本包支持无缝升级**，完全向后兼容。主要改进：\n- 保持所有注解和配置的兼容性\n- 增强了对 Route 包新特性的支持（如智能参数识别）\n- 优化了性能，但不改变任何公共接口\n- 自动适配 Route 包的 RESTful 增强特性\n\n**注意**：如果同时使用 Route 包，建议查看 Route 包的升级说明，因为路由生成规则有重大变化。\n\n## 🚀 快速开始\n\n### 1. 发布配置\n\n```bash\nphp bin/hyperf.php vendor:publish hyperf-plus/swagger\n```\n\n### 2. 基础配置\n\n编辑 `config/autoload/swagger.php`：\n\n```php\nreturn [\n    'enable' =\u003e true,\n    'port' =\u003e 9501,\n    'json_dir' =\u003e BASE_PATH . '/runtime/swagger/',\n    'html' =\u003e '/swagger',\n    'url' =\u003e '/swagger/openapi.json',\n    'auto_generate' =\u003e true,\n    'scan' =\u003e [\n        'paths' =\u003e [BASE_PATH . '/app'],\n    ],\n];\n```\n\n### 3. 使用示例\n\n```php\n\u003c?php\n\nuse HPlus\\Route\\Annotation\\ApiController;\nuse HPlus\\Route\\Annotation\\GetApi;\nuse HPlus\\Route\\Annotation\\PostApi;\nuse HPlus\\Validate\\Annotations\\RequestValidation;\nuse HPlus\\Swagger\\Annotation\\ApiDefinition;\nuse HPlus\\Swagger\\Annotation\\ApiServer;\n\n#[ApiController(tag: 'User Management')]\n#[ApiServer(url: 'http://localhost:9501', description: 'Development Server')]\nclass UserController\n{\n    #[GetApi(summary: '获取用户列表', description: '支持分页和搜索')]\n    #[RequestValidation(rules: [\n        'page|页码' =\u003e 'integer|min:1|default:1',\n        'size|每页数量' =\u003e 'integer|min:1|max:100|default:20',\n        'keyword|搜索关键词' =\u003e 'string|max:50'\n    ])]\n    public function index() {}\n    \n    #[PostApi(summary: '创建用户')]\n    #[RequestValidation(\n        rules: [\n            'username|用户名' =\u003e 'required|string|min:3|max:20',\n            'email|邮箱' =\u003e 'required|email',\n            'password|密码' =\u003e 'required|string|min:6'\n        ],\n        dateType: 'json'\n    )]\n    public function create() {}\n}\n```\n\n### 4. 访问文档\n\n启动服务后访问：`http://localhost:9501/swagger`\n\n## 📋 注解说明\n\n### @ApiDefinition\n\n定义数据模型（Schema）：\n\n```php\n#[ApiDefinition(\n    name: 'User',\n    type: 'object',\n    description: '用户模型',\n    properties: [\n        'id' =\u003e ['type' =\u003e 'integer', 'description' =\u003e '用户ID'],\n        'username' =\u003e ['type' =\u003e 'string', 'description' =\u003e '用户名'],\n        'email' =\u003e ['type' =\u003e 'string', 'format' =\u003e 'email'],\n        'profile' =\u003e [\n            'type' =\u003e 'object',\n            'properties' =\u003e [\n                'nickname' =\u003e ['type' =\u003e 'string'],\n                'avatar' =\u003e ['type' =\u003e 'string', 'format' =\u003e 'uri']\n            ]\n        ],\n        'status' =\u003e ['type' =\u003e 'string', 'enum' =\u003e ['active', 'inactive']],\n        'created_at' =\u003e ['type' =\u003e 'string', 'format' =\u003e 'date-time']\n    ],\n    required: ['id', 'username', 'email']\n)]\nclass UserSchema {}\n```\n\n### @ApiServer\n\n定义服务器信息：\n\n```php\n#[ApiServer(\n    url: 'https://api.example.com',\n    description: 'Production Server',\n    variables: [\n        'version' =\u003e [\n            'default' =\u003e 'v1',\n            'enum' =\u003e ['v1', 'v2'],\n            'description' =\u003e 'API Version'\n        ]\n    ]\n)]\n```\n\n### @ApiCallback\n\n定义回调信息：\n\n```php\n#[ApiCallback(\n    name: 'onUserCreated',\n    url: '{$request.body#/callback_url}',\n    method: 'POST',\n    requestBody: [\n        'user_id' =\u003e 'integer',\n        'event' =\u003e 'string'\n    ]\n)]\n```\n\n### @ApiLink\n\n定义链接关系：\n\n```php\n#[ApiLink(\n    name: 'GetUserById',\n    operationId: 'getUser',\n    parameters: [\n        'id' =\u003e '$response.body#/id'\n    ]\n)]\n```\n\n## 🎯 高级用法\n\n### 1. 响应示例\n\n使用 `@ApiResponse` 和 `@ApiResponseExample`：\n\n```php\nuse HPlus\\Route\\Annotation\\ApiResponse;\nuse HPlus\\Route\\Annotation\\ApiResponseExample;\n\n#[GetApi]\n#[ApiResponse(code: 200, description: '成功')]\n#[ApiResponseExample(\n    code: 200,\n    example: [\n        'code' =\u003e 0,\n        'message' =\u003e 'success',\n        'data' =\u003e [\n            'id' =\u003e 1,\n            'username' =\u003e 'john_doe'\n        ]\n    ]\n)]\npublic function show($id) {}\n```\n\n### 2. 请求体示例\n\n```php\nuse HPlus\\Route\\Annotation\\RequestBody;\n\n#[PostApi]\n#[RequestBody(\n    description: '用户信息',\n    required: true,\n    example: [\n        'username' =\u003e 'john_doe',\n        'email' =\u003e 'john@example.com',\n        'password' =\u003e 'secret123'\n    ]\n)]\npublic function create() {}\n```\n\n### 3. 文件上传\n\n```php\n#[PostApi(summary: '上传头像')]\n#[RequestValidation(\n    rules: [\n        'avatar' =\u003e 'required|file|image|max:2048'\n    ],\n    dateType: 'form'\n)]\npublic function uploadAvatar() {}\n```\n\n### 4. 安全认证\n\n```php\n// 全局安全配置\n#[ApiController(security: true)]\nclass SecureController {}\n\n// 方法级别配置\n#[GetApi(security: true)]\npublic function privateData() {}\n\n// 在配置文件中定义安全方案\n'security_schemes' =\u003e [\n    'bearerAuth' =\u003e [\n        'type' =\u003e 'http',\n        'scheme' =\u003e 'bearer',\n        'bearerFormat' =\u003e 'JWT'\n    ],\n    'apiKey' =\u003e [\n        'type' =\u003e 'apiKey',\n        'in' =\u003e 'header',\n        'name' =\u003e 'X-API-Key'\n    ]\n]\n```\n\n### 5. 分组和标签\n\n```php\n// 控制器级别标签\n#[ApiController(tag: 'User Management', description: '用户管理相关接口')]\n\n// 多标签支持\n#[GetApi(tags: ['User', 'Admin'])]\n\n// 标签描述（在配置中）\n'tags' =\u003e [\n    [\n        'name' =\u003e 'User Management',\n        'description' =\u003e '用户相关操作',\n        'externalDocs' =\u003e [\n            'description' =\u003e 'Find more info',\n            'url' =\u003e 'https://example.com/docs/user'\n        ]\n    ]\n]\n```\n\n## 🔧 配置详解\n\n### 完整配置示例\n\n```php\nreturn [\n    'enable' =\u003e env('SWAGGER_ENABLE', true),\n    'port' =\u003e 9501,\n    'json_dir' =\u003e BASE_PATH . '/runtime/swagger/',\n    'html' =\u003e '/swagger',\n    'url' =\u003e '/swagger/openapi.json',\n    'auto_generate' =\u003e true,\n    \n    // OpenAPI 基础信息\n    'info' =\u003e [\n        'title' =\u003e 'My API',\n        'version' =\u003e '1.0.0',\n        'description' =\u003e 'API Documentation',\n        'termsOfService' =\u003e 'https://example.com/terms',\n        'contact' =\u003e [\n            'name' =\u003e 'API Support',\n            'email' =\u003e 'support@example.com',\n            'url' =\u003e 'https://example.com/support'\n        ],\n        'license' =\u003e [\n            'name' =\u003e 'MIT',\n            'url' =\u003e 'https://opensource.org/licenses/MIT'\n        ]\n    ],\n    \n    // 服务器配置\n    'servers' =\u003e [\n        [\n            'url' =\u003e 'http://localhost:9501',\n            'description' =\u003e 'Development server'\n        ],\n        [\n            'url' =\u003e 'https://api.example.com',\n            'description' =\u003e 'Production server'\n        ]\n    ],\n    \n    // 安全方案\n    'security_schemes' =\u003e [\n        'bearerAuth' =\u003e [\n            'type' =\u003e 'http',\n            'scheme' =\u003e 'bearer',\n            'bearerFormat' =\u003e 'JWT'\n        ]\n    ],\n    \n    // 扫描配置\n    'scan' =\u003e [\n        'paths' =\u003e [\n            BASE_PATH . '/app/Controller',\n        ],\n        'ignore' =\u003e [\n            BASE_PATH . '/app/Controller/AbstractController.php',\n        ]\n    ],\n    \n    // 外部文档\n    'externalDocs' =\u003e [\n        'description' =\u003e 'Find out more',\n        'url' =\u003e 'https://example.com/docs'\n    ]\n];\n```\n\n## 🎨 UI 定制\n\n### 自定义 UI 配置\n\n```php\n'ui' =\u003e [\n    'title' =\u003e 'My API Documentation',\n    'favicon' =\u003e '/favicon.ico',\n    'css' =\u003e '/custom.css',\n    'js' =\u003e '/custom.js',\n    'theme' =\u003e 'dark', // light, dark\n    'tryItOutEnabled' =\u003e true,\n    'docExpansion' =\u003e 'list', // none, list, full\n    'defaultModelsExpandDepth' =\u003e 1,\n    'persistAuthorization' =\u003e true,\n]\n```\n\n## 🚀 性能优化\n\n1. **文档缓存**\n   ```php\n   'cache' =\u003e [\n       'enable' =\u003e true,\n       'ttl' =\u003e 3600, // 缓存时间（秒）\n       'dir' =\u003e BASE_PATH . '/runtime/swagger/cache/'\n   ]\n   ```\n\n2. **增量更新**\n   - 只更新修改的控制器\n   - 智能检测文件变化\n\n3. **生产环境优化**\n   ```php\n   'production' =\u003e [\n       'enable' =\u003e false, // 生产环境关闭自动生成\n       'cache_forever' =\u003e true, // 永久缓存\n   ]\n   ```\n\n## 🤝 与其他组件协作\n\n### Route 组件集成\n\n- 自动识别所有路由注解\n- 提取路径、方法、参数信息\n- 支持 RESTful 和自定义路径\n\n### Validate 组件集成\n\n- 自动转换验证规则为参数定义\n- 生成请求体 Schema\n- 提取字段描述和示例\n\n### 集成流程\n\n```\nRoute 注解 → 路由信息提取 ↘\n                          → Swagger 文档生成 → OpenAPI JSON → Swagger UI\nValidate 注解 → 参数信息提取 ↗\n```\n\n## 📝 最佳实践\n\n1. **文档质量**\n   - 为每个接口添加 summary 和 description\n   - 提供请求和响应示例\n   - 使用有意义的标签分组\n\n2. **版本管理**\n   - 使用版本前缀区分 API 版本\n   - 保持向后兼容\n   - 标记废弃的接口\n\n3. **安全考虑**\n   - 生产环境关闭自动生成\n   - 限制文档访问权限\n   - 不暴露敏感信息\n\n## 🐛 问题排查\n\n1. **文档不更新**\n   - 清除缓存：`php bin/hyperf.php swagger:clear`\n   - 检查自动生成是否开启\n   - 手动生成：`php bin/hyperf.php swagger:generate`\n\n2. **接口未显示**\n   - 确认控制器有 `@ApiController` 注解\n   - 检查扫描路径配置\n   - 验证注解语法正确\n\n3. **参数信息缺失**\n   - 确认 Validate 组件已安装\n   - 检查验证规则格式\n   - 查看生成的 JSON 文件\n\n## 🛠️ 命令行工具\n\n```bash\n# 生成文档\nphp bin/hyperf.php swagger:generate\n\n# 清除缓存\nphp bin/hyperf.php swagger:clear\n\n# 验证文档\nphp bin/hyperf.php swagger:validate\n\n# 导出文档\nphp bin/hyperf.php swagger:export --format=yaml\n```\n\n## 📄 许可证\n\nMIT License\n\n## 🤝 贡献\n\n欢迎提交 Issue 和 Pull Request！\n\n## 🔗 相关链接\n\n- [OpenAPI Specification](https://www.openapis.org/)\n- [Swagger UI](https://swagger.io/tools/swagger-ui/)\n- [Hyperf Documentation](https://hyperf.wiki/)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-plus%2Fswagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperf-plus%2Fswagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-plus%2Fswagger/lists"}