Yii框架需第三方扩展实现Swagger文档，推荐lichunqiang/yii2-swagger（轻量）或zircote/swagger-php（灵活但需手动集成）；注解path须与真实路由完全一致；控制器动作须为public actionXXX形式且未被禁用；生成命令与访问路径不可混淆，修改注解后必须重新生成swagger.json。
Yii 框架本身不内置 Swagger 文档生成功能，必须靠第三方扩展实现；选错扩展或路径配置不对，生成的文档和真实接口完全对不上——这是最常被忽略、也最致命的问题。
用哪个扩展？别踩 yii2-apidoc 这个坑
虽然 yiisoft/yii2-apidoc 名字带“apidoc”，但它实际是 Yii 官方用于生成 PHP 代码文档（类似 PHPDoc）的工具，不支持 OpenAPI/Swagger 格式输出，更不会渲染交互式 UI 页面。强行配进去，访问 /apidoc 只能看到类结构树，不是接口列表。
真正可用的主流选择只有两个：
-
lichunqiang/yii2-swagger：轻量、开箱即用，适合中小型项目，依赖 Swagger UI 3.x，配置简单但自定义能力弱 -
zircote/swagger-php+ 手动集成 Swagger UI：更灵活，支持 OpenAPI 3.0 全特性（比如文件上传、多 server 切换），但需要自己管理swagger.json生成流程
如果你要写 @OA\Get 这类注解，就必须用 zircote/swagger-php；如果只是快速看个列表，lichunqiang/yii2-swagger 更省事。
@OA\Get(path="...") 的 path 必须和路由完全一致
Yii2 路由可能带模块前缀、版本号、后缀（如 'suffix' => '.json'），而 Swagger 注解里的 path 不会自动继承这些配置——它就是硬编码字符串。
常见错误示例：
- 控制器路由实际是
GET /api/v1/users.json，但注解写了@OA\Get(path="/v1/users")→ 文档里点“Try it out”会 404 - 用了
UrlManager的rules把article/<id:></id:>映射到article/view，注解却写@OA\Parameter(name="id", in="path", ...)→ 文档显示路径参数，但实际请求根本没这个段
正确做法：打开浏览器开发者工具 Network 面板，看真实请求地址，**一字不差复制进 path**。带后缀就写 .json，有模块名就写 /api/v1/...，开头斜杠不能少。
控制器动作必须显式启用，否则扫描不到
zircote/swagger-php 是静态扫描 PHP 文件注释，它不运行 Yii 应用，也不读 actions() 配置。哪怕你写了 @OA\Get，如果对应方法不是 public 且命名以 action 开头（如 actionIndex），或者被 public function actions() 里删掉了，就不会出现在文档中。
检查要点：
- 方法名是否为
actionXXX形式（index,view,create等） - 是否声明为
public，且没有被父类actions()返回值排除（例如'delete' => false） - 若用
ActiveController，确保$modelClass指向的模型存在且可反射，否则参数 schema 可能为空
临时验证方法：在控制器里加一个空的 public function actionTest() {} 并打上注解，看是否出现在文档里——能出现，说明扫描通路没问题；不能出现，先查命名和可见性。
生成命令和访问路径容易混淆
zircote/swagger-php 需要命令行生成 JSON：php vendor/bin/openapi --output api/web/swagger-docs/swagger.json api/controllers/。这个命令不走 Yii 路由，只读文件，所以路径写错会导致“找不到类”或“空文档”。
而最终访问文档的 URL 和扩展强相关：
- 用
lichunqiang/yii2-swagger：访问http://localhost/index.php?r=swagger/default/index - 用
zircote/swagger-php+ 自托管 UI：访问http://localhost/swagger-ui/dist/index.html，且该 HTML 里url字段必须指向你生成的swagger.json路径（如/swagger-docs/swagger.json）
最容易卡住的点：改了注解但刷新页面没变化——不是缓存问题，是忘了重新运行生成命令，或者 index.html 里写的 JSON 路径 404（用浏览器 Network 面板看是否返回 404）。
