OpenAPI 版本治理与兼容（Deprecation、合同测试 与验证）

概述

API版本治理通过路径或头部表达版本, 使用弃用标记提示迁移窗口。合同测试在CI中校验请求与响应的Schema兼容, 防止破坏性变更。

关键实践与参数

• 版本策略: 路径 `/v1` `/v2` 或 `Accept-Version`
• 弃用声明: `deprecated: true` 并在文档中注明移除时间
• 兼容规则: 新增字段为可选, 保持类型与语义稳定
• 合同测试: 使用Schema校验请求/响应

示例/配置/实现

openapi: 3.0.3
info: { title: Shop API, version: "1.1.0" }
paths:
  /v1/items:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  name: { type: string }
                  desc: { type: string, deprecated: true }

import Ajv from 'ajv'
const ajv = new Ajv({ allErrors: true })
const schema = { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' } }, required: ['id', 'name'] }
const validate = ajv.compile(schema)
function test(resp) { return validate(resp) }

验证

• 兼容性: 旧客户端在新增字段为可选时仍正常工作
• 弃用提示: 文档与响应中明确标记弃用字段
• 合同测试: CI对主要接口进行Schema校验通过
• 发布安全: 不兼容变更被阻止或要求新版本路径

注意事项

• 版本窗口需明确与可见
• 避免静默移除字段, 提前通知并提供迁移指南
• 合同测试覆盖主路径与错误响应
• 与网关的路由与监控协同