在 VSCode 中可通过安装 Red Hat YAML 和 Swagger Viewer 扩展、配置 OpenAPI Schema 绑定、使用 Swagger: Preview 命令预览、运行 swagger-cli validate 验证及启用 Ctrl+Click 跳转与自动补全，实现 OpenAPI 文档的高效编写与交互式预览。
如果您希望在 Visual Studio Code 中高效编写和预览 API 文档，Swagger 或 OpenAPI 规范是主流选择。VSCode 本身不原生支持 OpenAPI 渲染，但可通过扩展与配置实现语法高亮、自动补全、实时预览及验证功能。以下是具体实施步骤：
本文运行环境：MacBook Pro，macOS Sequoia。
一、安装 OpenAPI 相关扩展
VSCode 需借助社区扩展识别 OpenAPI 文件格式（如 .yaml 或 .yml），提供结构化编辑支持。核心扩展可同时满足语法校验、缩进提示与文档跳转能力。
1、打开 VSCode，点击左侧活动栏的扩展图标（或按 Cmd+Shift+X）。
2、在搜索框中输入 Red Hat YAML，找到官方发布的 YAML Language Support by Red Hat 扩展并安装。
3、再次搜索 Swagger Viewer，安装由 Arjun Komath 提供的同名扩展，用于内联预览 OpenAPI 文档。
4、重启 VSCode 使扩展生效。
二、配置 YAML 扩展以识别 OpenAPI 文件
Red Hat YAML 扩展默认不将 .yaml 文件自动关联为 OpenAPI 模式，需手动指定文件关联与 Schema 绑定，从而启用语义验证与智能提示。
1、按下 Cmd+, 打开设置界面，点击右上角“打开设置（JSON）”图标。
2、在 settings.json 中添加以下配置项：
3、在 yaml.schemas 对象内插入键值对："https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json" 作为值，"*.yaml" 和 "*.yml" 作为键（可合并为数组）。
4、保存文件后，新建或打开任意 .yaml 文件，右下角状态栏应显示 YAML (OpenAPI) 模式。
三、使用 Swagger Preview 快速查看交互式文档
Swagger Viewer 扩展可在编辑器右侧以面板形式渲染 OpenAPI 定义，生成可折叠、可执行请求的 UI 界面，无需启动本地服务器。
1、确保当前打开的文件为合法 OpenAPI 3.x 格式的 YAML 文件（含 openapi: 3.1.0 字段）。
2、右键编辑器空白区域，选择 Swagger: Preview；或使用快捷键 Cmd+Shift+P，输入并执行命令 Swagger: Preview。
3、右侧将弹出预览面板，显示 Paths、Models 及 Try it out 功能区。
四、集成 OpenAPI Validator 进行静态检查
为避免语法错误导致后续工具链中断，建议引入独立验证器对 OpenAPI 文件进行即时校验。该方法不依赖图形界面，适合 CI/CD 前置检查场景。
1、在终端中执行 npm install -g @apidevtools/swagger-cli 安装命令行工具。
2、在 VSCode 中打开集成终端（Cmd+`），进入项目根目录。
3、运行命令 swagger-cli validate openapi.yaml，输出结果中若含 valid 字样，则表示通过基础结构验证。
五、启用自动补全与引用跳转
Red Hat YAML 扩展结合 OpenAPI Schema 绑定后，可识别 components/schemas、paths 等关键字，并支持跨文件引用补全与 Ctrl+Click 跳转定义。
1、在 OpenAPI 文件中定义一个 schema，例如在 components/schemas 下添加 User 对象。
2、在某条 path 的 requestBody 中引用该 schema：$ref: '#/components/schemas/User'。
3、将光标置于 $ref 值上，按住 Ctrl 键并单击，即可跳转至 User 定义处。
4、在 $ref: 后输入 #/ 并触发自动补全，列表中将显示所有可用路径节点。
