Yii2集成Swagger需手动组合zircote/swagger-php与Swagger UI：注解须写在public action上并含激活标记，路径须与实际URL完全一致，资源须通过AssetBundle发布，生成命令须显式指定目录。
Yii2 本身不带 Swagger 功能，必须靠第三方工具组合实现：用 zircote/swagger-php 扫描注解生成 JSON，再用 Swagger UI 渲染页面。整个过程不自动、不智能，路径要手写、资源要手动发布、命令要显式执行——规范就体现在这些“必须做”的细节里。
注解必须写在 action 上，且 path 一字不差
Swagger-php 是静态扫描器，完全不读 Yii2 的 UrlManager 或路由规则。哪怕你配置了 'article/<id:>' => 'article/view'</id:>，注解里也得硬写：
-
@OA\Get(path="/api/v1/articles/123")—— 实际请求 URL 是什么，这里就写什么 - 带后缀（如
.json）就得带上：/api/v1/users.json - 有模块前缀（如
v1）和 API 前缀（如/api）都不能省 - 参数只声明结构，不映射规则：
@OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"))就够了，不用写正则或占位符
控制器文件必须“激活”，注解才被识别
一个 PHP 文件里光有 @OA\Get 不够，还得有“激活标记”，否则 swagger-php 直接跳过该文件：
- 要么开头加
@OA\Info(title="My API", version="1.0") - 要么至少有一个
@OA\PathItem（比如配合@OA\Get一起出现） - 注解必须写在
public function actionIndex()方法上方，不能写在方法内部，也不能写在 private 方法上 - 如果控制器继承
yii\rest\ActiveController，别指望它自动推导接口——每个公开 action 都得单独加@OA\Get/@OA\Post
资源必须走 AssetBundle，不能直接扔进 webroot
Swagger UI 的 JS/CSS 必须通过 Yii2 的资源管理机制发布，否则页面空白或报 SwaggerUIBundle is not defined：
- 定义自定义 AssetBundle，
$sourcePath指向vendor/swagger-api/swagger-ui/dist - 设
publishOptions['forceCopy'] = true，避免缓存导致旧版 JS 加载失败 - 在布局文件
head区域调用SwaggerUiAsset::register($this) - F12 查 Network，确认
/assets/xxx/swagger-ui-bundle.js返回 200；若 404，删掉@web/assets目录重试
生成命令必须指定目录，不能靠猜测
运行 php vendor/bin/openapi 时，不传路径就不会扫任何代码：
- 正确示例：
php vendor/bin/openapi --output docs/api.json api/controllers/ modules/v1/controllers/ - 路径末尾不要加
*或通配符，openapi不支持 shell 展开，会当字面量处理 - Yii2 Starter Kit 类项目常有
api/modules/v1/controllers这种嵌套结构，漏掉就等于漏掉整版接口 - 修改注解后必须重新运行命令，
swagger.json不会自动更新
