Download the PHP package madong/swagger without Composer

Madong Swagger 模块

一个功能强大、结构清晰的 Swagger/OpenAPI 文档生成模块，专为 Webman 框架设计。

📋 目录

• 功能特性
• 目录结构
• 快速开始
• 注解分类
• 详细使用指南
• AnnotationHelper 使用
• IS_REPEATABLE 支持
• 最佳实践
• 向后兼容
• 常见问题
• 更新日志

✨ 功能特性

• 完整的 OpenAPI 3.0 支持：基于 zircote/swagger-php 和 webman-tech/swagger
• 清晰的注解分类：认证、操作、响应三类注解，职责分明
• 强大的响应注解：支持 6 种响应类型（Data、Page、List、Tree、Result、Simple）
• 权限注解集成：内置 AllowAnonymous 和 Permission 注解，支持权限中间件
• AnnotationHelper 工具：便捷获取控制器和方法的注解信息
• IS_REPEATABLE 支持：响应注解支持在同一个方法上重复使用
• 向后兼容：提供 core\attribute 别名类，兼容旧代码
• 灵活的示例数据：支持多种数据格式（类、对象、JSON、数组）

📁 目录结构

命名空间规范

重要：响应类（DataResponse、PageResponse 等）只在 annotation/response 中存在，没有对应的 attribute 版本。认证类则同时存在于 attribute 和 annotation/auth 中。

🚀 快速开始

1. 安装

2. 配置路由

在 app/adminapi/config/route.php 中注册 Swagger：

3. 创建 Schema

4. 在控制器中使用

5. 访问文档

启动服务后，访问：http://localhost:8787/adminapi/openapi

📚 注解分类详解

一、认证注解（attribute/ 或 annotation/auth/）

1. AllowAnonymous - 跳过认证

用于标记需要跳过 Token 验证或权限验证的接口。

推荐使用 attribute 命名空间：

属性说明：

• $requireToken (bool): 是否跳过 Token 验证，默认为 false
• $requirePermission (bool): 是否跳过权限验证，默认为 false
• $description (?string): 描述，用于文档生成

2. Permission - 权限注解

用于标记控制器或方法需要的权限。

属性说明：

• $code (string|array): 权限码，可以是字符串或数组
• $operation (string): 操作类型，and 或 or，默认为 and
• $description (?string): 权限描述，用于文档

方法说明：

• create(string $code): 创建单个权限
• all(array $codes): 创建 AND 关系的多个权限
• any(array $codes): 创建 OR 关系的多个权限
• getCodes(): array: 获取权限码列表
• getOperation(): string: 获取操作类型
• isAnd(): bool: 检查是否为 AND 操作
• isOr(): bool: 检查是否为 OR 操作

3. ValidationRule - 验证规则注解

用于在 Request 类的属性上定义验证规则，并可在 API 文档中展示验证信息。

属性说明：

• $rules (string|array): 验证规则
• $messages (array): 自定义错误消息
• $attributes (array): 字段名称映射
• $description (?string): 字段描述
• $example (mixed): 示例值

方法说明：

• getRulesString(): string: 获取验证规则字符串
• getRulesArray(): array: 获取验证规则数组
• hasRule(string $rule): bool: 检查是否包含指定规则
• getRulesDescription(): string: 获取规则描述（用于文档展示）

二、响应注解（annotation/response/）

所有响应注解都支持 IS_REPEATABLE，可以在同一个方法上重复使用，用于定义不同状态码的响应。

1. DataResponse - 数据对象响应

返回单个数据对象的响应模板。

参数说明：

• $schema (mixed): Schema 类名、类对象或 JSON 字符串
• $example (mixed): 示例值（JSON 字符串、数组或对象）
• $description (string): 响应描述
• $response (int): HTTP 状态码，默认为 200
• $headers (array): 响应头

响应格式：

2. PageResponse - 分页响应

返回分页数据的响应模板。

响应格式：

3. ListResponse - 列表响应

返回列表数据的响应模板。

响应格式：

4. TreeResponse - 树形数据响应

返回树形数据的响应模板。

响应格式：

5. ResultResponse - 通用结果响应

返回通用结果的响应模板。

参数说明：

• $jsonExample (?string): JSON 字符串示例
• $schema (?string): Schema 类名（可选）
• $dataExample (mixed): 数据示例（可选）
• $description (string): 响应描述
• $response (int): HTTP 状态码，默认为 200
• $headers (array): 响应头

6. SimpleResponse - 简单响应

返回简单成功消息的响应模板。

响应格式：

三、操作注解（annotation/operation/）

1. ApiOperation - 操作信息

2. ApiParameter - 参数定义

3. ApiRequestBody - 请求体

🔧 AnnotationHelper 使用

AnnotationHelper 提供了一组便捷方法来获取控制器和方法的注解信息，主要用于中间件和文档生成。

基本用法

完整 API

获取注解

检查注解

实际应用场景

场景 1：权限中间件

场景 2：文档生成

场景 3：API 元数据收集

🔄 IS_REPEATABLE 支持

问题描述

在 PHP 8 中，属性默认不允许在同一个目标上重复使用。如果需要在同一个方法上定义多个响应（例如不同状态码的响应），会出现以下错误：

解决方案

本模块已为所有响应注解添加了 Attribute::IS_REPEATABLE 标志，支持在同一个方法上重复使用。

使用示例

支持 IS_REPEATABLE 的注解

所有响应注解都支持重复使用：

• DataResponse
• PageResponse
• ListResponse
• TreeResponse
• ResultResponse
• SimpleResponse

不支持重复的注解

以下注解不需要重复，因此不添加 IS_REPEATABLE 标志：

• AllowAnonymous - 跳过认证（一个方法只需要一个）
• Permission - 权限（一个方法只需要一个）
• ValidationRule - 验证规则（用于属性）
• ApiOperation - 操作信息（一个方法只需要一个）

💡 最佳实践

1. 统一命名空间使用

推荐做法：

• 响应注解使用 madong\swagger\annotation\response\*
• 认证注解使用 madong\swagger\attribute\*

不推荐做法：

2. 合理使用响应注解重复

虽然支持重复，但建议根据实际业务需求合理使用：

推荐（2-3 个响应）：

不推荐（过多响应）：

3. 使用 ResponseHelper 简化代码

4. 权限注解的层级使用

类级别权限（作用于所有方法）：

方法级别权限（覆盖或补充类级别）：

5. 使用 ExampleHelper 生成示例数据

🔄 向后兼容

为了向后兼容，项目保留了 core\attribute 命名空间下的别名类：

• core\attribute\AllowAnonymous - 继承自 madong\swagger\attribute\AllowAnonymous
• core\attribute\Permission - 继承自 madong\swagger\annotation\auth\Permission

兼容性说明

旧代码（继续有效）：

新代码（推荐）：

注意： 响应类（DataResponse、PageResponse 等）没有 core\attribute 别名，因为它们主要在控制器中使用，不需要被中间件频繁查询。

❓ 常见问题

Q1: 为什么响应类只在 annotation/response 中，没有 attribute 版本？

A: 响应类主要用于控制器文档注解，不需要被中间件频繁查询。认证类（AllowAnonymous/Permission）需要被中间件频繁查询，因此提供 attribute 门面简化使用。

Q2: 使用 attribute 和 annotation/auth 有什么区别？

A: 没有区别，attribute\* 类继承自 annotation\auth\* 类，两者完全等价。推荐使用 attribute 命名空间，更简洁。

Q3: AnnotationHelper 获取注解时应该用哪个类？

A: 推荐统一使用 attribute\* 类：

Q4: 为什么我的响应注解还是提示不能重复？

A: 请检查：

1. 是否使用了正确的命名空间：

2. 是否重新生成了自动加载：

3. 是否更新了 vendor 目录：

Q5: 如何在中间件中获取注解？

A: 使用 AnnotationHelper：

Q6: 如何排除测试控制器不生成文档？

A: 在路由配置中排除：

📄 更新日志

v1.0.0 (2026-03-11)

新增功能

• ✅ 完整的 OpenAPI 3.0 支持
• ✅ 6 种响应注解（Data、Page、List、Tree、Result、Simple）
• ✅ 3 种认证注解（AllowAnonymous、Permission、ValidationRule）
• ✅ 3 种操作注解（ApiOperation、ApiParameter、ApiRequestBody）
• ✅ AnnotationHelper 注解查询工具
• ✅ ResponseHelper 响应注解创建工具
• ✅ ExampleHelper 示例数据生成工具
• ✅ SchemaHelper Schema 辅助工具

优化改进

• ✅ 优化目录结构：attribute（门面）+ annotation（实现）
• ✅ 添加 IS_REPEATABLE 支持，响应注解可重复使用
• ✅ 修复命名空间大小写问题
• ✅ 修复访问级别错误（private → protected）
• ✅ 添加向后兼容别名（core\attribute）

文档完善

• ✅ 完整的 README.md
• ✅ 命名空间规范指南
• ✅ IS_REPEATABLE 修复说明
• ✅ AnnotationHelper 使用示例
• ✅ 最佳实践指南

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🙏 致谢

• Webman - 高性能 HTTP 框架
• Swagger PHP - OpenAPI 注解库
• Webman Swagger - Webman Swagger 集成

📞 联系方式

• 作者：Mr. April
• 邮箱：[email protected]
• 官方网站：http://www.madong.tech
• Gitee：https://gitee.com/motion-code

Made with ❤️ by Madong