webstorm识别openapi.yaml必须手动设为openapi specification类型，仅靠文件名或后缀无效；底部状态栏显示“yaml”即识别失败，需右键→override file type→openapi specification，并验证paths:行alt+insert弹出http图标菜单才算生效。
WebStorm 识别 openapi.yaml 必须手动设为 OpenAPI Specification 类型
光看文件名或后缀没用，openapi.yaml 默认被当成普通 YAML 文件处理。底部状态栏显示 YAML 就是识别失败的明确信号——此时没有语法校验、@OA\Get 补全、路径跳转，更不会出现 Preview 标签页。
必须右键该文件 → Override File Type → 选择 OpenAPI Specification。验证是否生效：把光标放在 paths: 行，按 Alt+Insert（macOS 是 Cmd+N），弹出菜单里有带 HTTP 方法图标的选项才算成功。
常见错误：
- 只勾选了 Settings → Languages & Frameworks → OpenAPI Specifications 中的
Enable OpenAPI Specifications support，但漏掉Enable preview - 项目里用了
@SWG\Get却没在插件设置里配置前缀（PHPStorm 场景下需额外指定注解别名） - YAML 缩进混用 Tab 和空格，导致预览空白或报
mapping values are not allowed here
Preview 标签页不出现？检查三个硬性前提
Preview 标签页不是“点一下就出来”的功能，它依赖三件事同时成立：
- 文件后缀必须是
.yaml或.json（.yml不被识别） - 文件类型已被强制设为
OpenAPI Specification（见上一条） - Settings → Languages & Frameworks → OpenAPI Specifications 中
Enable preview已勾选
缺一不可。哪怕只漏一个，右上角就永远看不到那个 Preview 标签页。别怀疑插件没装对——WebStorm 2021.3+ 内置支持，不需要额外装 Swagger 插件（那是 PHPStorm 场景才需要的）。
Preview 渲染结果为空白或结构错乱？优先查 YAML 合法性
WebStorm 的 Preview 是纯静态解析器，不运行任何代码，也不调用外部工具。它直接读取文本内容并渲染树形结构，所以对格式极其敏感。
最常踩的坑：
- 缩进用了 Tab 而非空格（YAML 规范强制要求空格）
- 字符串值里有未闭合的单引号或双引号，比如
description: 'This is a broken string -
$ref指向了不存在的相对路径，例如$ref: './components/schemas/User.yaml'，但该文件实际在./schemas/User.yaml - 注释写在行尾且后面紧跟冒号，如
type: string # required—— 这会破坏解析
建议用在线 YAML 验证器（如 https://yamlchecker.com/）先过一遍，再回 WebStorm 看 Preview。
别指望 Preview 替代 Swagger UI
Preview 只展示文档结构，不发起请求，不代理后端，不支持 server.url 动态替换，也不渲染 example 值或 schema 的图形化描述。
真正容易被忽略的是：当你用 @OA\Get 注解生成文档时，Preview 显示的内容取决于你当前打开的 openapi.yaml 文件；而 Swagger UI 显示的是后端运行时实时生成的文档。两者不同步是常态——改了注解但忘了 php artisan l5-swagger:generate，或者改了 YAML 但后端没重启，就会看到两套完全不同的接口列表。
