应安装 zircote/swagger-php：composer require zircote/swagger-php；生成命令为 ./vendor/bin/swagger [源码路径] --output [输出目录]；注解须统一用 @OA\ 前缀，JSON 需通过 Swagger UI 静态托管访问。
Composer 本身不提供 Swagger 文档生成功能，它只是 PHP 的依赖管理工具；真正生成文档的是 swagger-php（注解式）或 zircote/swagger-php（官方维护分支），配合 swagger-ui 渲染。直接运行 composer install swagger 会失败——因为没这个包。
如何用 Composer 安装 swagger-php 并支持注解解析
必须安装的是 zircote/swagger-php，它是目前主流的 PHP 注解驱动 Swagger/OpenAPI 生成器。它不依赖 Laravel 或 Symfony，但需要 PHP 7.4+ 和反射扩展启用。
- 在项目根目录执行：
composer require zircote/swagger-php
- 确保你的 PHP 环境已启用
php-json和php-reflection扩展（绝大多数环境默认开启） - 不要安装
swagger-api/swagger-php（已废弃，最后更新于 2016 年） - 如果项目用 Laravel，可额外加
darkaonline/l5-swagger，但它本质是封装了zircote/swagger-php+ UI 集成
生成 JSON 文档时常见的路径与命令错误
swagger-php 是命令行工具，但不是全局命令；它由 Composer 自动注册到 vendor/bin/swagger。直接敲 swagger 会报“command not found”，除非你配置了 $PATH。
- 正确调用方式（推荐相对路径）：
./vendor/bin/swagger app/Http/Controllers --output storage/api-docs
-
app/Http/Controllers是 Laravel 典型控制器路径；请按你实际代码结构替换，例如src/Api或modules/v1 - 输出目录（
--output）必须存在且可写，否则报failed to open stream: Permission denied - 若提示
Class 'OpenApi\Annotations\OpenApi' not found，说明用了旧版注解命名空间，应统一为@OA\OpenApi（对应use OpenApi\Annotations as OA;）
如何让生成的 JSON 被 Swagger UI 正确加载
生成的 openapi.json 只是数据，需前端 UI 渲染。Swagger UI 不是 PHP 包，不能靠 Composer 自动部署；常见做法是静态托管或反向代理。
- 下载最新 Swagger UI：从 GitHub Releases 解压
dist/目录到项目public/swagger-ui/ - 在
public/swagger-ui/index.html中修改url指向你的 JSON 路径，例如：url: "/storage/api-docs/openapi.json"
- 确保 Web 服务器允许访问
storage/api-docs/（Laravel 默认禁止，需在public/storage建软链或配置 Nginx alias） - 别把
openapi.json放在storage/app/下——它不在公开路径，Nginx/Apache 默认拒访
最易被忽略的是注解语法版本和 OpenAPI 版本绑定关系：@OA\Get 对应 OpenAPI 3.x，不兼容 Swagger 2.0 注解（如 @SWG\Get）；混用会导致解析中断且无明确报错。检查你所有控制器注解是否全部以 @OA\ 开头，并确认 zircote/swagger-php 版本 ≥ 4.0。
