使用VS Code进行API文档编写（Swagger/OpenAPI）-VSCode-PHP中文网

使用VS Code进行API文档编写（Swagger/OpenAPI）

P粉986688829

发布： 2025-11-29 20:23:02

原创

148人浏览过

安装OpenAPI Editor、Swagger Viewer等扩展后，在VS Code中编写YAML格式的OpenAPI文件，可实现实时语法检查、自动补全与内联预览，通过Prettier格式化并验证结构正确性，提升文档准确性与协作效率。

使用vs code进行api文档编写（swagger/openapi）

用 VS Code 写 API 文档，尤其是基于 Swagger（即 OpenAPI）规范时，效率和准确性都能大幅提升。VS Code 提供了丰富的插件支持、语法高亮、自动补全和实时预览功能，让编写 OpenAPI 文档变得更直观、更少出错。

安装必要的扩展

要高效编写 OpenAPI 文档，先在 VS Code 中安装几个关键扩展：

OpenAPI (Swagger) Editor：由42Crunch提供，支持 YAML 和 JSON 格式的 OpenAPI 文件，具备语法检查、自动补全和错误提示。
Swagger Viewer：可以内联预览 Swagger UI 界面，无需启动服务器就能查看文档效果。
YAML：微软官方扩展，增强 YAML 文件的编辑体验，包括格式化和验证。
Prettier：统一代码风格，可配置用于自动格式化 OpenAPI 文件。

创建并编辑 OpenAPI 文件

新建一个 openapi.yml 或 swagger.json 文件。推荐使用 YAML，结构更清晰易读。

输入基本框架：

openapi: 3.0.3
info:
  title: 示例 API
  version: 1.0.0
  description: 一个简单的用户管理 API
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户数组
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

登录后复制

编辑过程中，扩展会实时提示字段拼写错误、结构问题或缺失必填项。