Yii框架需用zircote/swagger-php加自定义AssetBundle实现Swagger，注解须手动写在action上且路径严格匹配真实URL，资源须通过AssetBundle发布，生成命令需显式指定源码目录。
Yii 框架本身不内置 Swagger 支持，必须靠第三方扩展实现；主流选择是 zircote/swagger-php（静态分析） + 自定义 AssetBundle（UI 渲染），而不是“开箱即用”的模块。强行用 yii2-swagger 这类过时封装，反而容易卡在路由映射、资源发布或 PHP 版本兼容上。
注解必须手动写在 action 方法上方，不能依赖 Yii2 路由规则
Swagger-php 是纯静态扫描工具，完全不读取 UrlManager、rules 或模块嵌套配置。哪怕你配置了 '，注解里也得硬写 @OA\Get(path="/users/123")，且路径要和真实请求 URL 完全一致——包括前缀（如 /v1）、后缀（如 .json）、斜杠结尾与否。
-
@OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"))就够了，不用写正则 - 如果控制器继承
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。别信“应该能自动对齐”，它不会。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
