swagger-php是将PHP代码结构自动转为OpenAPI文档的工具，推荐使用PHP 8.2+属性语法（如#[OAT\Get]），弃用Doctrine注解；需确保命名空间为OpenApi\Attributes、路径扫描准确、响应体通过DTO类+ref方式定义，避免手动重复写Schema。
swagger-php 不是“学语法”的编程语言，它是一套把 PHP 代码里的结构和类型信息，自动翻译成 OpenAPI 文档的工具。你不需要从零写文档，而是让代码自己“说话”。关键不是背注解，而是理解怎么用它避免文档和代码脱节。
用 PHP 属性还是 Doctrine 注解？
PHP 属性（#[OAT\Get]）是当前唯一推荐的方式。Doctrine 注解（/** @OA\Get */）已被标记为弃用，且依赖 doctrine/annotations 库，运行时解析慢、IDE 支持差、类型检查弱。
必须确认你的项目满足：
- PHP 版本 ≥ 8.2
- 使用 OpenApi\Attributes 命名空间（不是 OpenApi\Annotations）
- Composer 安装后，vendor/zircote/swagger-php/src/Attributes/ 目录存在
常见错误：
- 混用命名空间：写了 use OpenApi\Attributes as OA; 却在注解里用 @OA\Get（这是注解写法，会报错）
- 在 PHP 8.1 以下环境硬用属性，直接 Parse Error
立即学习“PHP免费学习笔记（深入）”；
生成命令跑不起来？先查这三件事
vendor/bin/openapi 是入口，但失败往往不是命令本身的问题：
- 路径没指定对：默认不递归扫描子目录，
vendor/bin/openapi app只扫app目录下的一级文件，控制器在app/Http/Controllers就会被漏掉——得写全vendor/bin/openapi app/Http/Controllers - 自动加载缺失：如果类没被 Composer 自动加载（比如某些测试类或独立脚本），加
--bootstrap vendor/autoload.php强制引入 - 输出路径权限不足：
-o public/swagger.json要求public/目录可写；Windows 下路径分隔符写成反斜杠\也会静默失败
响应体写不对？别手动写 Schema
最常踩的坑是花半小时手写 #[OAT\Schema] 描述返回数组，结果字段名拼错、类型写成 string 但实际是 int，还和 DTO 类不一致。
正确做法：
- 给返回数据建一个标准 DTO 类（如 UserResponse）
- 在方法上用 #[OAT\Response(..., schema: new OAT\Schema(ref: '#/components/schemas/UserResponse'))]
- 然后单独给该 DTO 类加 #[OAT\Schema] 注解，字段一一对应
这样改字段只需动 DTO 类 + 其注解，不会漏掉 API 方法里的描述。Swagger-PHP 6+ 还支持从 PHP 类型提示自动推断（如 public function getUser(): UserResponse），但仅限简单标量和嵌套对象，复杂结构仍需显式注解。
文档里看不到参数或 404 错误？检查注解作用域
#[OAT\Parameter] 必须和 #[OAT\Get] 或其他 HTTP 方法属性写在同一个方法上，不能提上去放在类或 trait 里——它不会继承，也不会跨作用域生效。
典型错误场景：
- 把所有通用参数（如 X-Api-Version）集中定义在一个 trait 中，再 use 进控制器 → 不生效
- 在父控制器写了 #[OAT\Parameter]，子类继承但没重写方法 → 子类方法无参数
- 路径参数 {id} 写了 #[OAT\Parameter(in: 'path')]，但方法签名没声明 public function show(string $id) → 文档里参数名变成 id，但类型是 string（正确）还是 object（错误）取决于是否能反射到参数类型
真正难的不是写对单个注解，而是让整个项目的注解组织方式能随代码演进而稳定同步——比如 DTO 类改了字段，有没有机制确保所有引用它的 ref 都被检查？这已经超出 swagger-php 本身能力范围，得靠团队约定 + CI 检查。
