2. OpenAPI 基础结构：核心对象与作用

OpenAPI 规范（原 Swagger 规范）是描述 RESTful API 的事实标准。一个合法的 OpenAPI 文档必须包含 openapi 字段，并在此基础上组织 info、servers、paths、components 等顶层对象。理解这五个基础结构，是编写可维护、可自动生成客户端与文档的 API 描述文件的前提。

2.1 openapi 字段：版本声明

openapi 字段位于文档根节点，用于声明所遵循的 OpenAPI 规范版本。该字段的值必须是语义化版本号（SemVer），例如 3.0.3 或 3.1.0。它是整个文档的入口标识，解析器据此决定如何解析后续对象。

openapi: "3.0.3"
info:
  title: 订单服务 API
  version: "1.2.0"
servers:
  - url: https://api.example.com/v1
paths:
  /orders:
    get:
      summary: 获取订单列表
      responses:
        '200':
          description: 成功返回订单数组
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string

2.2 info 对象：元数据描述

info 对象提供 API 的元数据，包括标题、版本、描述、联系人信息和许可信息。该对象是文档的“身份牌”，在生成文档首页和 SDK 时被广泛使用。

2.3 servers 对象：访问地址

servers 对象是一个数组，定义 API 的基 URL（Base URL）。每个服务器条目包含 url（必填）和 description（可选），支持变量模板（如 {environment}）实现多环境切换。

servers:
  - url: https://api.prod.example.com/v2
    description: 生产环境
  - url: https://api.staging.example.com/v2
    description: 预发布环境
  - url: https://{subdomain}.example.com/{basePath}
    description: 动态环境
    variables:
      subdomain:
        default: api
        enum: [api, api-dev, api-test]
      basePath:
        default: v2

在 Kafka 堆积诊断场景中，servers 对象常用于区分不同集群的监控 API 入口，例如生产集群与沙箱集群使用不同的 URL 模板。

2.4 paths 对象：API 端点定义

paths 对象是 OpenAPI 文档的核心，以相对路径为键，映射到该路径上支持的 HTTP 方法（GET、POST、PUT、DELETE 等）。每个方法下可定义参数、请求体、响应、安全要求等。

• 路径模板： 支持 {param} 占位符，如 /orders/{orderId}。
• 操作对象： 每个 HTTP 方法对应一个 Operation Object，包含 summary、operationId、parameters、requestBody、responses。
• 响应对象： 必须至少定义一个成功响应（通常为 200 或 201），推荐为每个错误码定义描述。

paths:
  /orders:
    get:
      operationId: listOrders
      summary: 分页查询订单
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 订单列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '400':
          description: 参数错误
  /orders/{orderId}:
    get:
      operationId: getOrderById
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 单个订单详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

2.5 components 对象：可复用组件

components 对象是 OpenAPI 的“工具箱”，用于定义可复用的 Schema、参数、响应、请求体、安全方案等。通过 $ref 引用，避免在多个路径中重复定义相同结构。

2.6 五对象关系总览

以下 SVG 图展示了 OpenAPI 文档顶层五个对象之间的依赖与引用关系，帮助理解它们在文档中的位置与协作方式。

2.7 工程实践要点

• 版本对齐： 始终在 info.version 中记录 API 文档版本，并通过 CI 流水线确保与代码版本一致。
• 服务器模板化： 使用 servers.variables 实现多环境切换，避免手动修改 URL。
• 路径设计： 路径参数使用 {param} 占位符，查询参数在 parameters 中定义，避免硬编码。
• 组件复用： 将通用 Schema（如分页响应、错误结构）放入 components.schemas，减少重复代码。
• Kafka 集成： 在监控 API 的 OpenAPI 文档中，使用 components.schemas 定义 ConsumerGroup、TopicPartition、Lag 等模型，便于生成客户端 SDK。