VSCode集成OpenAPI文档可视化预览-VSCode-PHP中文网

vscode 1.77+原生支持openapi 3.x预览，无需swagger插件；需手动设语言模式为openapi specification、配置v3.1 schema、确保文件以openapi:开头且含info/paths字段，$ref引用文件也须满足相同要求。

vscode集成openapi文档可视化预览

VSCode 1.77+ 版本已原生支持 OpenAPI 3.x 文档的可视化预览，不需要装 Swagger Viewer、OpenAPI Preview 等过时或不兼容插件——它们多数只认 swagger: "2.0"，遇到 openapi: 3.1.0 直接报空或报错。

没按钮不是插件没装对，是文件没被识别为 OpenAPI 文档。VSCode 默认把 openapi.yaml 当普通 YAML 处理，必须手动“认领”。

右键打开的文件 → Change Language Mode → 选 OpenAPI Specification（不是 YAML 或 JSON）
右下角状态栏应立刻变成 OpenAPI Specification；若仍显示 YAML，说明这步没成功
首次设置后，可点右上角齿轮图标 → Configure File Association for '.yaml' → 输入 openapi 确认，以后同名后缀自动绑定
如果点了 Preview 还弹 No OpenAPI definition found，大概率是文档缺 info 或 paths 字段——这两个是硬性必需，空对象 {} 也得有

$ref: './components/schemas/User.yaml' 报错，90% 不是路径写错了，而是被引用文件没通过 OpenAPI 入口校验。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

所有被 $ref 引用的 YAML 文件（如 User.yaml）第一行**必须是** openapi: 3.1.0 或 openapi: 3.0.3，不能省略
路径只能用正斜杠 /，.\components\schemas\User.yaml 在 Windows 上也得改成 ./components/schemas/User.yaml
不支持 $ref: 'https://...'，VSCode 不发起网络请求，本地开发一律用相对路径
检查文件是否真实存在：macOS/Linux 区分大小写，user.yaml 和 User.yaml 是两个文件；Windows 上注意隐藏后缀（比如实际是 User.yaml.txt）

要，但只为了补全和校验，不是为了预览——预览靠 VSCode 原生能力，而校验靠它。

打开 settings.json，加这段（注意 URL 必须是 v3.1，不是 v3.0）：

"yaml.schemas": {
  "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json": ["*.yaml", "*.yml"]
}

最易被忽略的一点：VSCode 的 OpenAPI 预览器对缩进极其敏感，paths 下一级必须严格用空格缩进（不能混 Tab），且字段顺序无关，但结构层级错一格，整个区块就可能被跳过——预览里只剩空白，问题面板却未必报红。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！