PHP 8.5 尚未发布，当前最新稳定版是 PHP 8.3；swagger-php v4.x 支持 PHP 8.1–8.3，依赖反射和属性语法，所谓“PHP 8.5 兼容”仅为占位话术，实际可用组合为 PHP 8.3 + swagger-php ^4.9 + OpenAPI UI。
PHP 8.5 尚未发布，目前（截至 2024 年中）最新稳定版是 PHP 8.3；Swagger 本身不直接“生成”文档，它依赖 OpenAPI 规范，而 PHP 生态中真正起作用的是 swagger-php 这类注解解析器——你写的不是 Swagger，是符合 OpenAPI 的 PHP 注解。
为什么 swagger-php 在 PHP 8.3+ 能用，但别信“PHP 8.5 支持”这种说法
官方 swagger-php（v4.x）已明确支持 PHP 8.1–8.3，底层依赖反射 API 和属性（#[Attribute]），这些在 PHP 8.5 发布前根本不存在。所谓“PHP 8.5 兼容”，只是未来版本的占位话术。你现在能用的组合就是：PHP 8.3 + swagger-php ^4.9 + openapi-ui（如 Swagger UI 或 Redoc）。
- PHP 8.4 引入了只读类（
readonly class）和更严格的类型推导，swagger-phpv4.x 尚未适配——这意味着哪怕 PHP 8.4 正式发布，你也得等swagger-phpv5 才能安全使用新语法 - PHP 8.3 的
#[\Override]、enum枚举值注解已可被swagger-php解析，但需显式启用useOpenApiAttributes=true配置 - 如果你强行在 PHP 8.3 环境下用
swagger-phpv3.x，会报错Attribute "OpenApi\Annotations\Get" is not allowed——因为 v3 不认识 PHP 8.1+ 的原生属性语法
@OA\Get 和 #[OA\Get] 到底该用哪个
两者都有效，但语义和维护成本不同。PHP 8.1+ 推荐用原生属性（#[OA\Get]），它更轻量、IDE 支持更好、且不会被 PHPDoc 解析器误吞；传统 PHPDoc 注解（@OA\Get）仍兼容，但必须确保注释块紧贴函数/类声明上方，中间不能有空行或其它注释干扰。
- ✅ 正确（属性语法，推荐）：
#[OA\Get( path: "/users", summary: "获取用户列表", responses: [ new OA\Response(response: "200", description: "OK") ] )] - ⚠️ 易错（PHPDoc 语法）：
/** * @OA\Get( * path="/users", * summary="获取用户列表", * @OA\Response(response="200", description="OK") * ) */
——注意：@OA\Response必须写在@OA\Get内部，不能拆成两个独立注释块；否则解析器只会看到第一个，丢掉响应定义 - ❌ 错误：
#[OA\Get(path: "/users")]单独写在 trait 方法上，但该方法未被控制器实际调用——swagger-php默认只扫描 public 方法，且不递归解析 trait 引入的逻辑，除非你手动配置analysis: Analysis::TYPES_ALL
运行 openapi 命令时输出空 JSON 或报 TypeError: ReflectionUnionType::__toString()
这是 PHP 8.3 中 ReflectionUnionType 字符串化行为变更导致的典型问题，常见于你用了联合类型（如 string|int|null）但 swagger-php 版本太低。v4.8.17 之前版本无法正确处理 PHP 8.3 的联合类型反射。
立即学习“PHP免费学习笔记（深入）”；
- 立刻升级：
composer update zircote/swagger-php --with-all-dependencies，确保最终安装的是v4.9.0+ - 检查是否意外启用了
opcache.enable=1且未清除缓存——swagger-php依赖实时反射，OPcache 可能缓存旧的类结构，导致注解丢失；开发环境建议临时设为opcache.enable=0 - 如果接口参数用了
#[MapFrom("x-api-key")]这类自定义属性，swagger-php默认忽略它们——你需要自己写Processor类并注册到Generator，否则字段不会出现在文档中
最常被跳过的一步：生成的 openapi.json 必须通过静态服务（如 Nginx 的 location /docs { alias /path/to/openapi.json; }）或后端路由暴露，不能靠前端直接读取 ./openapi.json——浏览器同源策略会拦截本地 file:// 协议请求。Swagger UI 页面和 JSON 文件必须同域。
