Yii集成Swagger生成REST文档步骤

Yii框架集成Swagger生成REST文档并非开箱即用，而是必须严格协同第三方扩展（zircote/swagger-php）、精准的手动OpenAPI注解（需写在控制器方法上方、使用@OA\*根注解激活文件、路径必须硬编码匹配真实请求URL）以及规范的静态资源发布（通过自定义AssetBundle强制发布Swagger UI并确保JS/CSS正确加载）——任一环节缺失都会导致文档空白、404、JSON生成失败或路径错乱；尤其要注意注解与Yii路由配置的“双重维护”无法自动化，每次调整UrlManager规则或模块结构都必须同步更新注解中的path，否则文档与实际接口将严重脱节。

Yii 框架本身不自带 Swagger 文档生成功能，必须靠第三方扩展 + 手动注解 + 静态资源发布三者协同才能跑通。光装包、光写注解、光配路由，任意一环断掉都会导致页面空白、404、JSON 生成失败或路径错乱。

zircote/swagger-php 注解必须写在方法上方，且文件要被“激活”

Swagger-php 是静态扫描工具，不会运行 Yii 的类或路由逻辑。它只认 PHP 文件里有没有以 @OA\Info、@OA\PathItem 等开头的注解——没有这类“根注解”，整个文件会被跳过。

• 控制器方法前必须加 @OA\Get / @OA\Post 等动作注解，不能只依赖 yii\rest\ActiveController 的自动映射
• 注解必须写在 public function actionIndex() 这一级，不能塞进 actions() 数组里，也不能写在方法体内
• 如果把注解单独抽到 api/controllers/swagger.php 这类非控制器文件中，得确保 php vendor/bin/openapi 命令显式扫到它，例如：php vendor/bin/openapi --output docs/api.json api/controllers/ api/controllers/swagger.php
• PHP 版本低于 5.4？别用 [] 写数组，改用 array()，否则注解解析直接静默失败

路径必须硬编码，和 Yii2 的 UrlManager 完全无关

Swagger-php 不读 rules，不看模块嵌套，不解析 路由规则。所有 path 值必须是最终请求时浏览器实际发出的 URL，一个字符都不能差。

• @OA\Get(path="/v1/users") 就只能匹配 GET /v1/users，不能写成 /users 指望框架补前缀
• 若配置了 'suffix' => '.json'，路径就得写成 /v1/users.json，否则文档里的路径和真实接口对不上
• 参数绑定如 在路由中生效，但 Swagger 注解里只需声明 @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"))，不用管正则
• 模块路径如 api/modules/v1/controllers/UserController，对应 URL 是 /v1/users，不是 /api/v1/users —— 前缀取决于 UrlManager 配置，你得自己确认并写死

Swagger UI 静态资源必须手动发布，不能靠 @webroot 直接扔进去

直接把 swagger-ui/dist 整个目录丢进 @webroot 是最常见翻车点：Yii2 的 AssetBundle 机制会拦截请求，未注册的资源路径一律 404。

• 必须定义自定义 AssetBundle，$sourcePath 指向 vendor/swagger-api/swagger-ui/dist
• 加上 publishOptions['forceCopy'] = true，避免因缓存导致 JS/CSS 未更新
• 在布局文件（如 @app/views/layouts/main.php）的 区域调用 SwaggerUiAsset::register($this)，否则控制台报 SwaggerUIBundle is not defined
• F12 查 Network，确认 /assets/xxx/swagger-ui-bundle.js 返回 200；若 404，删掉 @web/assets 目录再刷新一次

生成命令必须显式指定源码目录，别信“自动发现”

php vendor/bin/openapi 默认只扫当前目录，不递归，也不识别 Yii2 的命名空间结构。不指定路径，大概率生成空 JSON 或只扫到部分文件。

• 正确命令示例：php vendor/bin/openapi --output docs/api.json api/modules/v1/controllers/ api/controllers/
• 如果用了多模块（如 v1、v2），每个模块路径都要列出来，不能只写 api/modules
• 输出路径 docs/api.json 必须可写，且 Web 服务器能通过 HTTP 访问到（比如放在 @web/docs/api.json）
• 生成后检查 JSON 是否合法：用在线校验器或 jq .info.title docs/api.json 看是否能读出字段；若报错，八成是某处注解语法错误（比如少了个括号、引号没闭合）

最容易被忽略的是注解与路由的“双重维护”：每次改 UrlManager 规则或模块结构，Swagger 注解里的 path 就得同步改。没人能绕过这点，也没人能靠工具自动推导——因为那不是静态分析能做到的事。

今天关于《Yii集成Swagger生成REST文档步骤》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！