OpenAPI 3.0 核心概念与定义基础

OpenAPI 规范（原 Swagger 规范）是描述 RESTful API 的行业标准接口描述语言。在消息队列任务复测场景中，OpenAPI 3.0 为任务提交、状态查询、结果回调等操作提供了机器可读的契约定义，是集成验证的基石。

3.1 OpenAPI 3.0 核心概念

OpenAPI 3.0 文档围绕以下核心对象构建，每个对象对应 API 生命周期中的一个关键维度：

3.2 YAML / JSON 定义方式

OpenAPI 3.0 支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、注释友好，成为教学和文档编写的首选；JSON 则更适合程序解析和传输。两者可无损互转。

YAML 定义示例（推荐）：

openapi: 3.0.3
info:
  title: 消息队列任务复测 API
  version: "1.0.0"
  description: 用于提交、查询和回调消息队列任务复测结果的接口规范
servers:
  - url: https://api.mq-replay.io/v1
    description: 生产环境
paths:
  /tasks:
    post:
      summary: 提交复测任务
      operationId: submitTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskRequest'
      responses:
        '201':
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
components:
  schemas:
    TaskRequest:
      type: object
      required:
        - queueName
        - messagePayload
      properties:
        queueName:
          type: string
          description: 目标消息队列名称
        messagePayload:
          type: string
          description: 待复测的消息体（Base64 编码）
    TaskResponse:
      type: object
      properties:
        taskId:
          type: string
          format: uuid
          description: 复测任务唯一标识
        status:
          type: string
          enum: [pending, running, completed, failed]

JSON 等价定义（片段）：

{
  "openapi": "3.0.3",
  "info": {
    "title": "消息队列任务复测 API",
    "version": "1.0.0"
  },
  "paths": {
    "/tasks": {
      "post": {
        "summary": "提交复测任务",
        "operationId": "submitTask",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskRequest"
              }
            }
          }
        }
      }
    }
  }
}

3.3 路径与操作对象

路径对象（Path Item）是 API 端点的容器，操作对象（Operation）则定义该端点支持的 HTTP 方法及其行为。在消息队列任务复测中，典型的路径-操作映射如下：

每个操作对象内部可包含 parameters（路径参数、查询参数）、requestBody（请求体）、responses（响应定义）以及 security（操作级安全策略）。

paths:
  /tasks/{taskId}:
    get:
      summary: 查询复测任务状态
      operationId: getTaskStatus
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功返回任务状态
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatus'
        '404':
          description: 任务不存在

3.4 请求与响应模型

请求模型和响应模型通过 components/schemas 定义，并在路径操作中通过 $ref 引用。这种解耦设计使得模型可以在多个端点间复用，降低维护成本。

请求模型设计要点：

• 必填字段：使用 required 数组声明，如 queueName、messagePayload
• 数据格式：使用 format 约束，如 uuid、date-time、byte（Base64）
• 枚举约束：使用 enum 限定状态值，如 [pending, running, completed, failed]

响应模型设计要点：

• 状态码覆盖：至少定义 2xx（成功）、4xx（客户端错误）、5xx（服务端错误）三类响应
• 错误结构：统一使用 ErrorResponse 模型，包含 code、message、details 字段
• 分页支持：列表查询响应应包含 items、totalCount、page、pageSize

components:
  schemas:
    TaskStatus:
      type: object
      properties:
        taskId:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, running, completed, failed]
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: 任务完成百分比
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: 错误码，如 TASK_NOT_FOUND
        message:
          type: string
          description: 人类可读的错误描述
        details:
          type: object
          description: 可选的错误详情上下文

3.5 请求与响应模型在消息队列场景中的特殊设计

消息队列任务复测涉及异步处理，请求与响应模型需要额外考虑以下设计模式：