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

应安装 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 'OpenApiAnnotationsOpenApi' not found，说明用了旧版注解命名空间，应统一为 @OAOpenApi（对应 use OpenApiAnnotations 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 版本绑定关系：@OAGet 对应 OpenAPI 3.x，不兼容 Swagger 2.0 注解（如 @SWGGet）；混用会导致解析中断且无明确报错。检查你所有控制器注解是否全部以 @OA 开头，并确认 zircote/swagger-php 版本 ≥ 4.0。