使用VS Code和Swagger插件编写和预览API文档

安装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 插件提供缩进提示和错误检查，确保格式正确。

AIBox 一站式AI创作平台

AIBox365一站式AI创作平台，支持ChatGPT、GPT4、Claue3、Gemini、Midjourney等国内外大模型

217

查看详情

使用 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 结构。

以上就是使用VS Code和Swagger插件编写和预览API文档的详细内容，更多请关注php中文网其它相关文章！