📚 课程目录第2章 OpenAPI基础

2. OpenAPI 基础：RESTful API 设计原则、OpenAPI 规范（Swagger）简介、API 文档自动生成

在构建任务调度平台时，前端控制台、CLI 工具、第三方集成都需要与后端服务进行标准化通信。本章将围绕 RESTful API 设计原则、OpenAPI 规范 以及 API 文档自动生成 三个核心知识点展开，为后续使用 Temporal 编排任务时的接口契约设计打下基础。

2.1 RESTful API 设计原则

REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，强调资源导向、无状态和统一接口。在任务调度平台中，我们将任务、工作流、队列等视为资源，通过标准 HTTP 方法进行操作。

原则	说明	任务调度平台示例
资源导向	每个 URL 代表一个资源，而非动作	`/api/tasks/{taskId}` 代表单个任务
统一接口	使用标准 HTTP 方法（GET/POST/PUT/DELETE）	`POST /api/tasks` 创建任务
无状态	每个请求包含所有必要信息，服务端不保存客户端上下文	请求头携带认证 Token，不依赖 Session
可缓存	响应隐式或显式标记为可缓存或不可缓存	任务列表支持 `ETag` 和 `Cache-Control`
分层系统	客户端无法直接感知是否与最终服务器或中间层通信	API 网关 → 任务服务 → Temporal Worker

  设计避坑： 不要在 URL 中使用动词（如 /api/getTask），应使用名词复数形式（如 /api/tasks）并通过 HTTP 方法表达动作。错误码应使用标准 HTTP 状态码（200、201、400、404、500），避免自定义 200 + 业务错误码混用。

2.2 OpenAPI 规范（Swagger）简介

OpenAPI 规范（原 Swagger 规范）是描述 RESTful API 的行业标准，使用 JSON 或 YAML 格式定义端点、请求参数、响应结构、认证方式等。它让 API 成为“可读的契约”，便于前后端协作和工具链集成。

2.2.1 核心结构

一个标准的 OpenAPI 文档包含以下顶层字段：

openapi：规范版本号，当前稳定版为 3.0.3 或 3.1.0。
info：API 标题、版本、描述。
servers：基础 URL 列表，支持多环境（开发、测试、生产）。
paths：所有端点的定义，按路径组织。
components：可复用的 schema、参数、响应、安全方案。

最佳实践： 将 components/schemas 中的模型定义与 paths 分离，避免重复定义相同数据结构。例如任务对象 Task 在创建、查询、更新时共享同一 schema。

2.2.2 任务调度平台 API 示例片段

openapi: "3.0.3"
info:
  title: 任务调度平台 API
  version: "1.0.0"
  description: 用于创建、查询和管理异步任务及工作流
servers:
  - url: https://api.scheduler.example.com/v1
paths:
  /tasks:
    get:
      summary: 获取任务列表
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, running, completed, failed]
      responses:
        '200':
          description: 任务列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
    post:
      summary: 创建新任务
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
      responses:
        '201':
          description: 任务创建成功
          headers:
            Location:
              schema:
                type: string
                format: uri
components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum: [pending, running, completed, failed]
        createdAt:
          type: string
          format: date-time
    CreateTaskRequest:
      type: object
      required: [name, workflowType]
      properties:
        name:
          type: string
        workflowType:
          type: string
        input:
          type: object

2.3 API 文档自动生成

基于 OpenAPI 规范，可以自动生成交互式文档、客户端 SDK、服务端桩代码和测试用例。主流工具链包括：

工具	用途	输出形式
Swagger UI	交互式 API 文档浏览与测试	Web 页面，支持在线发送请求
Swagger Editor	在线编写和校验 OpenAPI 规范	实时语法检查 + 预览
OpenAPI Generator	生成多语言客户端 SDK 和服务端代码	Java、Python、Go、TypeScript 等
Redoc	生成美观的静态 API 文档	单页 HTML，适合发布
Stoplight	可视化 API 设计与管理平台	协作式设计 + 文档 + Mock

注意： 自动生成的文档质量取决于 OpenAPI 规范的完整性和准确性。务必为每个端点添加 summary、description、parameters 和 responses 的详细定义，避免生成“无描述”的接口文档。

2.4 从 OpenAPI 到 Temporal 任务编排的桥梁

在任务调度平台中，OpenAPI 文档不仅服务于前端和外部集成，更是 Temporal 工作流与外部系统交互的契约基础。下图展示了 OpenAPI 规范如何贯穿整个平台架构：

2.5 本章小结

RESTful 原则 是任务调度平台 API 设计的基石，资源导向、统一接口、无状态是核心约束。
OpenAPI 规范 提供了机器可读的 API 契约，支持多语言工具链自动生成文档、SDK 和 Mock。
API 文档自动生成 大幅降低前后端协作成本，确保接口定义与实现始终同步。
在后续章节中，我们将基于 OpenAPI 规范定义 Temporal 工作流的触发接口，实现从 HTTP 请求到任务编排的完整链路。