1. OpenAPI 契约基础

1.1 OpenAPI 规范概述

OpenAPI 规范（原 Swagger 规范）是一种用于描述 HTTP API 的标准化、语言无关的接口定义格式。它允许开发者以机器可读的方式定义 API 的端点、请求参数、响应结构、认证方式等元数据，从而在服务提供方与消费方之间建立一份可验证的“契约”。

OpenAPI 规范的主要版本包括：

在缓存场景中，OpenAPI 契约承担了以下关键角色：

• 缓存键定义：通过 parameters、headers 明确哪些输入影响缓存键。
• 缓存时长声明：利用 response headers 或扩展字段标注 Cache-Control、Expires。
• 缓存失效边界：通过 operationId 与 tags 建立资源依赖关系，指导缓存清理。

1.2 YAML / JSON 语法基础

OpenAPI 规范支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、注释友好，成为编写契约的首选；JSON 则常用于程序间交换与存储。

1.2.1 格式对比

1.2.2 核心语法示例

以下是一个描述缓存相关 API 的 OpenAPI 3.0 片段，展示 YAML 与 JSON 的对应关系：

# YAML 版本
openapi: "3.0.3"
info:
  title: 缓存示例 API
  version: "1.0.0"
paths:
  /users/{userId}:
    get:
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回用户信息
          headers:
            Cache-Control:
              schema:
                type: string
                example: "public, max-age=3600"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

// JSON 等价版本
{
  "openapi": "3.0.3",
  "info": {
    "title": "缓存示例 API",
    "version": "1.0.0"
  },
  "paths": {
    "/users/{userId}": {
      "get": {
        "operationId": "getUserById",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回用户信息",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "public, max-age=3600"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" }
        }
      }
    }
  }
}

1.3 API 文档与契约的关系

在传统开发中，“API 文档”与“API 契约”常被混用，但在缓存架构语境下，二者有本质区别：

在缓存设计实践中，契约比文档更重要：

• 缓存键生成：契约中的 parameters、headers 定义直接决定缓存键的组成部分。
• 缓存策略自动化：通过解析契约中的 Cache-Control、ETag、Last-Modified 声明，可自动配置网关或 CDN 缓存规则。
• 契约即真相：当缓存策略与契约冲突时，以契约为准，避免因文档过时导致缓存误配置。