@oa\get注解不生效主因是文件未被swagger-php扫描到，需确保注解位于控制器方法上方、文件含@oa\info等激活注解，并显式指定源码路径；swagger不读取yii2路由规则，路径须硬编码且与实际请求完全一致。
为什么 @OA\Get 注解不生效，生成的文档里没接口？
根本原因通常是 PHP 文件没被 zircote/swagger-php 扫描到——它只解析带 @OA\ 注解的 PHP 类/方法，且默认不递归扫描 vendor 或未在配置中声明的路径。
- 确认注解写在控制器方法上方（不是 action 方法内部），且类已用
@OA\Info或至少一个@OA\PathItem开头的注解“激活”了该文件 - 运行生成命令时，显式指定源码目录：
php vendor/bin/openapi --output docs/api.json api/controllers/，别依赖自动发现 - Yii2 控制器常继承
yii\rest\ActiveController，但zircote/swagger-php不会自动识别其动作映射；必须为每个公开接口手动加@OA\Get/@OA\Post等注解，不能只靠路由规则 - 检查是否用了短数组语法
[]而非array()—— 旧版 PHP（如 5.4 以下）会直接跳过注解解析，报错但不提示
SwaggerUiAsset 加载后页面空白或 404？
这是 Yii2 资源发布和路径映射最常翻车的地方：Swagger UI 的静态资源没正确暴露到 Web 可访问路径。
- 不要把
swagger-ui-dist直接丢进@webroot下手动链接——Yii2 资源包机制会覆盖或冲突 - 必须定义自定义 AssetBundle，继承
yii\web\AssetBundle，并在$sourcePath指向vendor/swagger-api/swagger-ui/dist，再通过publishOptions['forceCopy'] = true强制复制 - 确保
AppAsset或布局文件中调用了SwaggerUiAsset::register($this)，且注册时机在head区域（否则 JS 报SwaggerUIBundle is not defined） - 浏览器 F12 查 Network，看
/assets/xxx/swagger-ui-bundle.js是否返回 200；如果 404，说明资源未发布成功，删掉@web/assets目录重试
如何让 Swagger 自动读取 Yii2 的 rules 路由配置？
不能。Swagger-php 是静态分析工具，完全不感知 Yii2 运行时的 URL 规则、模块嵌套或 UrlManager 配置。所有路径必须硬编码在注解里。
-
@OA\Get(path="/v1/users")中的/v1/users必须和实际请求路径完全一致（含前缀、斜杠结尾等），不能写成/users然后指望 Yii2 自动补v1 - 若项目启用了
'suffix' => '.json'，路径就得写成/v1/users.json，否则文档和真实接口对不上 - 参数绑定如
<code>id在路由中是<code><id:></id:>，但 Swagger 注解里只需声明@OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"))，不用管正则 - 想减少重复？用 PHP 常量或配置项拼接路径字符串，例如
path=API_V1_PREFIX."/users"，但注意注解值必须是字面量，不能是变量表达式
生成的 JSON 文档里 securitySchemes 不显示 Bearer Auth？
因为 @OA\SecurityScheme 必须定义在文件级（类上方），且需在接口注解中显式引用，Yii2 的行为过滤器（如 authenticator）不会被自动提取。
- 在任意一个控制器类顶部加：
@OA\SecurityScheme(securityScheme="BearerAuth", type="http", scheme="bearer", bearerFormat="JWT") - 每个需要鉴权的接口，加上
@OA\Security(requirements={{"BearerAuth"={}}}) - 如果用了自定义 Header（比如
X-API-Key），scheme改成apiKey，并设in="header"和name="X-API-Key" - 注意大小写：
securityScheme名称（这里是"BearerAuth"）必须和@OA\Security里的 key 完全一致，否则关联失败
rm -rf @web/assets/*，比查文档快。大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
