composer如何安装并在项目中使用Swagger生成API文档_composer实战教程【教程】-composer-PHP中文网

应安装 zircote/swagger-php：composer require zircote/swagger-php；生成命令为 ./vendor/bin/swagger [源码路径] --output [输出目录]；注解须统一用 @OA\ 前缀，JSON 需通过 Swagger UI 静态托管访问。

composer如何安装并在项目中使用swagger生成api文档_composer实战教程【教程】

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。