Yii框架集成Swagger生成API文档教程

本文深入解析了在Yii框架中集成Swagger生成高质量API文档的完整实践路径，强调必须摒弃过时封装、直面核心约束：使用zircote/swagger-php进行静态注解分析，严格手动编写与真实URL完全一致的OpenAPI注解（包括版本前缀、后缀和斜杠规范），通过自定义AssetBundle可靠发布Swagger UI资源，并显式指定源码目录执行生成命令；同时揭示了PHP版本兼容、路径一致性、注解激活条件等极易踩坑的关键细节，为开发者提供一套稳定、可复现、生产就绪的集成方案。

Yii 框架本身不内置 Swagger 支持，必须靠第三方扩展实现；主流选择是 zircote/swagger-php（静态分析） + 自定义 AssetBundle（UI 渲染），而不是“开箱即用”的模块。强行用 yii2-swagger 这类过时封装，反而容易卡在路由映射、资源发布或 PHP 版本兼容上。

注解必须手动写在 action 方法上方，不能依赖 Yii2 路由规则

Swagger-php 是纯静态扫描工具，完全不读取 UrlManager、rules 或模块嵌套配置。哪怕你配置了 '' => 'view'，注解里也得硬写 @OA\Get(path="/users/123")，且路径要和真实请求 URL 完全一致——包括前缀（如 /v1）、后缀（如 .json）、斜杠结尾与否。

• @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")) 就够了，不用写正则 ，那只是 Yii2 内部用的
• 如果控制器继承 yii\rest\ActiveController，别指望它自动推导 GET /users 对应 actionIndex() —— 必须为每个公开方法单独加 @OA\Get/@OA\Post 注解
• 注解文件必须被“激活”：要么有 @OA\Info，要么至少一个 @OA\PathItem，否则整个文件会被跳过

资源发布失败是页面空白的最常见原因

Swagger UI 的 JS/CSS 不是从 vendor/ 直接加载的，必须通过 Yii2 的 AssetBundle 机制发布到 @web/assets/ 下。直接把 swagger-ui-dist 扔进 @webroot 会导致 404 或资源覆盖冲突。

• 定义自定义 AssetBundle，$sourcePath 指向 vendor/swagger-api/swagger-ui/dist
• 设 publishOptions['forceCopy'] = true，避免因缓存导致旧版资源残留
• 在布局文件 head 区域调用 SwaggerUiAsset::register($this)，否则浏览器报 SwaggerUIBundle is not defined
• F12 查 Network，确认 /assets/xxx/swagger-ui-bundle.js 返回 200；若 404，删掉 @web/assets 目录重试

生成命令必须显式指定源码目录，不能靠自动发现

运行 php vendor/bin/openapi 时，不传 --output 和输入路径，它不会默认扫 @app/controllers。尤其 Yii2 Starter Kit 这类结构带 modules 或 api/controllers 的项目，漏目录就等于漏接口。

• 正确命令示例：php vendor/bin/openapi --output docs/api.json api/controllers/ modules/v1/controllers/
• 确保路径末尾不带 * 或通配符，openapi 不支持 shell 展开，会当字面量处理
• 如果用了短数组语法 [] 但 PHP 版本低于 5.4，注解解析直接静默失败，生成空 JSON —— 检查 PHP 版本，必要时改回 array()

最易被忽略的是路径一致性：Swagger 文档里的 path 值、Yii2 实际可访问的 URL、以及前端调用时拼的地址，三者必须一字不差。少个 v1、多一个 .json、斜杠开头或结尾不统一，都会导致文档能打开、但调试请求 404。别信“应该能自动对齐”，它不会。

到这里，我们也就讲完了《Yii框架集成Swagger生成API文档教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Yii框架的知识点！