OpenAPI 设计指南：从手动构建 JSON/YAML 到可视化设计

OpenAPI 规范（原名 Swagger 规范）是描述 REST API 的标准格式。它使用 JSON 或 YAML 格式定义 API 的端点、请求参数、响应结构等信息，让开发者能够清晰地了解和使用 API。

OpenAPI 规范的核心组成

一个完整的 OpenAPI 文档包含以下主要部分：

基本信息

API 标题、版本、描述
服务器地址和协议

openapi: 3.0.0
info:
  title: 用户管理 API
  version: 1.0.0
  description: 提供用户注册、登录、信息查询等功能
servers:
  - url: https://api.example.com/v1
    description: 生产环境

路径定义

HTTP 方法（GET、POST、PUT、DELETE 等）
请求路径和参数
请求体结构
响应格式和状态码

paths:
  /users/{id}:
    get:
      summary: 获取用户信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 返回用户信息

数据模型

定义请求和响应中使用的数据结构
字段类型、必填项、验证规则

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
      required:
        - id
        - name

安全配置

认证方式（API Key、OAuth2、JWT 等）
权限控制

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - ApiKeyAuth: []

传统的设计方式

直接编写 OpenAPI 文档需要手动构建 JSON 或 YAML 文件。以一个用户信息查询接口为例：

openapi: 3.0.0
info:
  title: 用户管理 API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: 获取用户信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回用户信息
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  email:
                    type: string

这种方式对于复杂的 API 来说，编写和维护都比较困难，容易出现格式错误或遗漏。