Yii框架集成Swagger需第三方扩展、手动注解和静态资源发布三者协同：注解须写在方法上方并用@OA\Info等激活文件，路径须硬编码匹配实际请求URL，Swagger UI资源须通过自定义AssetBundle强制发布。
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，不看模块嵌套，不解析 <id:></id:> 路由规则。所有 path 值必须是最终请求时浏览器实际发出的 URL，一个字符都不能差。
-
@OA\Get(path="/v1/users")就只能匹配GET /v1/users，不能写成/users指望框架补前缀 - 若配置了
'suffix' => '.json'，路径就得写成/v1/users.json，否则文档里的路径和真实接口对不上 - 参数绑定如
<id:></id:>在路由中生效，但 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）的<head>区域调用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 就得同步改。没人能绕过这点，也没人能靠工具自动推导——因为那不是静态分析能做到的事。
