PHP项目需用swagger-php生成API文档，核心是正确安装zircote/swagger-php和openapi/openapi、配置PSR-4自动加载、使用完整命名空间@OAGet注释并紧贴函数声明，再通过命令行生成openapi.json并配合Swagger UI静态托管使用。
PHP 项目没法自动出 API 文档，不是因为语言不行，而是你没用对工具链——swagger-php 是目前最稳定、兼容性最好、且能真正和 PHP 注释深度绑定的方案，别被各种“一键生成”宣传带偏，它本质是「注释即文档」，不是魔法。
怎么让 @OAGet 这类注释被识别出来
核心是装对包、配对自动加载、写对命名空间。很多人跑不起来，卡在第一步：注释压根没被扫描到。
-
composer require zircote/swagger-php（注意不是swagger-php-dev或其他 fork） - 确保你的控制器/接口类文件被
autoload覆盖（比如放在src/下且composer.json里有"psr-4": {"App\": "src/"}） - 所有 OpenAPI 注释必须用完整命名空间：
@OAGet，不是@Get或@SWGGet（v2 写法已废弃） - 注释必须紧贴在函数上方，中间不能空行；如果函数是
public function store(Request $request)，注释就得贴在function行之前
为什么 OpenApiAnnotations 报错或不生效
这是最常被忽略的依赖问题：v4+ 版本的 swagger-php 不再自带 OpenApiAnnotations 类，它被拆到了独立包 openapi/openapi 中。
- 执行
composer require openapi/openapi（v2.0+ 必须装） - 检查
vendor/zircote/swagger-php/src/Annotation.php是否存在；若不存在，说明装的是旧版或损坏包 - 如果你用 IDE（如 PhpStorm），手动在注释里写
@OAGet后没自动补全，大概率是没装openapi/openapi，补全依赖这个包里的 PHPDoc stubs - 别手动
use OpenApiAnnotations as OA——swagger-php的扫描器只认全局命名空间下的@OAXxx
怎么生成 openapi.json 并接入 Swagger UI
生成是命令行单步操作，但路径和入口点容易设错；Swagger UI 则建议静态托管，别试图用 PHP 输出 HTML。
立即学习“PHP免费学习笔记（深入）”；
- 运行命令：
./vendor/bin/openapi --output docs/openapi.json app/Http/Controllers/（路径指向你放控制器的目录） - 生成后检查
openapi.json里是否有"openapi": "3.0.3"和真实paths，没有就说明扫描路径不对或注释格式非法 - 把 Swagger UI 下载解压到
public/docs/，修改其index.html中的url字段为"/docs/openapi.json" - 别用
file://直接打开 UI——浏览器会因 CORS 拒绝读取本地 JSON；必须走 Web 服务器（如php -S localhost:8000）
最难的从来不是生成 JSON，而是让每个 @OAResponse 真实反映你的 return response()->json(...) 结构；手写 @OASchema 描述模型字段时，漏掉 required 或类型写成 string 但实际是 integer，前端联调时才会暴露——这部分没法自动生成，得人盯。
