WebStorm 内置 OpenAPI 支持需手动启用：在 Settings → Languages & Frameworks → OpenAPI Specifications 中勾选“Enable OpenAPI Specifications support”和“Enable preview”，并确保 openapi.yaml 等文件被正确识别为 OpenAPI 规范（底部状态栏显示 OpenAPI 3.0），否则无语法校验、跳转、补全及右上角 Preview 标签页。
WebStorm 本身不支持 Swagger 文档预览，必须手动启用 OpenAPI 支持并确保文件类型被正确识别，否则 openapi.yaml 或 swagger.json 打开后只是普通文本，没有语法校验、跳转、补全，也看不到右上角的 Preview 标签页。
确认 WebStorm 已启用 OpenAPI 插件
WebStorm 自 2021.3 起内置了 OpenAPI 支持，但默认可能未开启。不是靠装第三方插件，而是要打开内置功能：
- 进入
Settings → Languages & Frameworks → OpenAPI Specifications - 勾选
Enable OpenAPI Specifications support - 确保
Enable preview也被勾选（否则即使文件类型对了，也看不到预览页签） - 如果项目里已有
openapi.yaml，此时右键它 →Override File Type → OpenAPI Specification，强制识别
验证文件是否被识别为 OpenAPI Specification
识别失败是预览不可用的最常见原因。别只看后缀名，得看 IDE 底部状态栏或文件图标：
- 打开
openapi.yaml，底部状态栏应显示OpenAPI 3.0或类似标识；若显示YAML，说明未识别成功 - 光标放在
paths:行，按Alt+Insert（macOS 是Cmd+N），应出现带get/post图标的弹出菜单 —— 这是识别生效的明确信号 - 若没反应，右键文件 →
Override File Type → OpenAPI Specification，再试一次
打开 Preview 标签页并理解它的限制
预览功能仅渲染本地 YAML/JSON 文件结构，不发起任何 HTTP 请求，也不代理后端服务：
- 文件被正确识别后，编辑器右上角会出现
Preview标签页，点击即可查看折叠式文档树和接口列表 - 它不支持
server.url动态替换，所有$ref必须指向项目内可访问的相对路径（如./components/schemas/User.yaml） - 若预览空白或报错，检查 YAML 缩进是否合规（必须用空格，不能用 Tab），以及是否有未闭合的引号或注释位置错误
- 它不替代 Swagger UI；想调试请求，仍需启动后端并访问
/swagger-ui.html或部署 Redoc
真正容易被忽略的是：WebStorm 的 OpenAPI 预览和后端运行时的 Swagger UI 完全是两套机制。前者纯静态解析，后者依赖 Springfox/NestJS 等框架实时生成文档。混用时，常因 openapi.yaml 手动维护与代码注解不同步导致预览内容和实际接口对不上。
