2. OpenAPI 规范基础：OpenAPI Specification (OAS) 版本演进、核心结构、YAML/JSON 语法

OpenAPI 规范（OAS）是定义 HTTP API 的标准接口描述语言，它独立于编程语言，既可供人类阅读，也可被机器解析。在分布式任务调度平台中，OAS 是契约一致性的核心载体——调度中心与执行器、管理端与 SDK 之间的所有交互，都依赖一份精确的 OAS 文档来约束请求/响应结构、状态码和错误模型。

2.1 OAS 版本演进与选型建议

OAS 经历了从 Swagger 2.0 到 OpenAPI 3.0/3.1 的演进。不同版本在表达能力、复用机制和 JSON Schema 兼容性上存在显著差异。

2.2 OAS 核心结构：从根对象到路径

一份完整的 OAS 文档由顶层对象和若干核心区块组成。以下 SVG 展示了 OAS 3.1 的顶层结构及其关系：

OAS 文档的顶层字段必须包含 openapi（版本声明）、info（元信息）和 paths（路径定义）。servers 和 components 为推荐字段，webhooks、tags、externalDocs 为可选字段。

2.3 YAML / JSON 语法与选择

OAS 支持 YAML 和 JSON 两种序列化格式。在分布式任务调度平台的实践中，YAML 因可读性高、支持注释、适合人工编写而成为首选；JSON 则常用于程序生成和网络传输。

2.3.1 语法对比

2.3.2 典型 YAML 示例：任务提交接口

以下代码片段展示了一个分布式任务调度平台中“提交任务”端点的 OAS 3.1 定义，使用 YAML 格式：

openapi: "3.1.0"
info:
  title: 分布式任务调度平台 API
  version: "2.0.0"
  description: 用于任务提交、查询、停止及执行器管理的契约接口

servers:
  - url: https://api.scheduler.example.com/v2
    description: 生产环境

paths:
  /tasks:
    post:
      summary: 提交新任务
      operationId: submitTask
      tags:
        - 任务管理
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskSubmitRequest'
      responses:
        '201':
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskSubmitResponse'
        '400':
          description: 请求参数校验失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 调度服务暂不可用

components:
  schemas:
    TaskSubmitRequest:
      type: object
      required:
        - taskName
        - executorType
        - command
      properties:
        taskName:
          type: string
          description: 任务名称，全局唯一
          example: "data-export-20250321"
        executorType:
          type: string
          enum: [shell, python, docker, http]
          description: 执行器类型
        command:
          type: string
          description: 执行命令或入口脚本
        timeout:
          type: integer
          description: 超时时间（秒）
          default: 300
        retryCount:
          type: integer
          description: 失败重试次数
          default: 0
    TaskSubmitResponse:
      type: object
      properties:
        taskId:
          type: string
          description: 调度系统生成的唯一任务 ID
        status:
          type: string
          enum: [queued, running, completed, failed]
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

2.4 路径与操作：HTTP 方法的契约映射

每个路径下可包含一个或多个 HTTP 方法操作（get、post、put、delete、patch 等）。每个操作必须定义 operationId（唯一标识）、parameters（路径/查询/头参数）、requestBody（仅适用于 post/put/patch）和 responses（至少一个成功响应）。

以下 SVG 展示了路径 /tasks/{taskId} 上 GET 和 DELETE 两个操作的内部结构：

2.5 数据模型与复用机制

components/schemas 是 OAS 契约一致性的基石。在分布式任务调度平台中，以下模型通常被定义为可复用的 Schema：

• Task：任务核心属性（ID、名称、类型、状态、优先级、创建时间）
• Executor：执行器注册信息（名称、地址、标签、心跳时间）
• TaskLog：任务执行日志（行号、时间戳、级别、内容）
• Pagination：分页请求（page、size、sort）和分页响应（total、items）
• ErrorResponse：统一错误结构（code、message、traceId）

2.6 契约一致性检查清单

在编写或评审 OAS 文档时，可使用以下清单快速验证基础质量：