安装Swagger Viewer和YAML插件后，可在VS Code中编写并实时预览OpenAPI文档，通过右键点击api.yaml选择Preview Swagger即可查看交互式界面，结合Prettier格式化与自动保存功能，提升API设计效率。
使用 VS Code 和 Swagger 插件编写和预览 API 文档是一个高效、直观的过程，特别适合开发 RESTful 接口时实时查看和调试文档。通过合适的插件支持，你可以在编辑 OpenAPI（原 Swagger）规范文件时即时预览生成的 API 文档界面，提升协作与开发效率。
安装必要的插件
在 VS Code 中实现 Swagger 编辑与预览，需要安装以下推荐插件：
- Swagger Viewer (by Arjun)：允许你在 VS Code 内部预览 Swagger/OpenAPI 文件的可视化文档。
- YAML（由 Red Hat 提供）：提供语法高亮、自动补全和格式校验，适用于 YAML 格式的 OpenAPI 定义文件。
- Prettier 或 YAML Formatter：帮助格式化代码，保持文档结构清晰。
打开 VS Code，进入扩展商店（快捷键 Ctrl+Shift+X），搜索并安装上述插件。
创建 OpenAPI/Swagger 文件
在项目根目录下创建一个名为 api.yaml 或 swagger.json 的文件。以下是一个简单的 OpenAPI 3.0 示例（YAML 格式）：
openapi: 3.0.0
info:
title: 示例 API
version: 1.0.0
description: 用于演示 VS Code 中 Swagger 预览功能
servers:
- url: http://localhost:3000/api
paths:
/users:
get:
summary: 获取用户列表
responses:
'200':
description: 成功返回用户数组
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
保存文件后，VS Code 会根据 YAML 插件提供缩进提示和错误检查，确保格式正确。
使用 Swagger Viewer 预览文档
安装并启用 Swagger Viewer 插件后，右键点击你创建的 api.yaml 文件，在上下文菜单中选择 Preview Swagger。VS Code 将在侧边栏打开一个可视化页面，展示类似 Swagger UI 的交互式文档界面。
在这个预览界面中，你可以：
- 查看所有定义的接口路径和请求方法
- 展开每个接口查看参数、响应结构和示例
- 了解整体 API 结构，便于前后端协作沟通
提高编写效率的小技巧
为了更顺畅地编写 OpenAPI 文档，可以采用以下实践：
- 使用 .yaml 而非 .json，YAML 更易读写，适合手动编辑。
- 开启 VS Code 的自动保存功能（File → Auto Save），避免频繁手动保存。
- 利用 YAML 插件的折叠功能收起不关注的部分，聚焦当前编辑内容。
- 参考官方 OpenAPI 规范文档，确保字段使用符合标准，避免预览失败。
基本上就这些。配置完成后，你就可以在 VS Code 中流畅地编写、校验并实时预览 API 文档，无需切换到浏览器或启动额外服务。这种方式特别适合设计阶段快速迭代 API 结构。
