OpenAPI契约与JSON Schema演进治理

概览

• OpenAPI 3.0/3.1 与 JSON Schema 联合描述接口；契约是跨团队协作与演进基础。
• 通过兼容策略与验证工具在迭代中保护下游。

技术参数（已验证）

• 版本：OpenAPI 3.1 与 JSON Schema 兼容增强；$schema 与 $ref 管理复用与组合。
• 约束：required、enum、format 与 additionalProperties；采用 oneOf/anyOf/allOf 表达变体。
• 兼容性：Backward/Forward/Full；避免移除/重命名，使用新增与可选字段。
• 验证：在 CI 中执行 schema 校验与示例测试；对破坏性变更阻断。
• 文档与生成：与代码生成工具协同；保持契约与实现一致。

实战清单

• 建立契约仓库与审查流程；记录变更与影响分析。
• 在发布前进行兼容性检查与示例回归；出具变更说明与 Sunset 路线。
• 对异常变更建立快速回滚与告警。

OpenAPI 演进

通过契约管理与 JSON Schema 版本化实现 API 的向后兼容演进。

• oneOf / anyOf / allOf 组合
• deprecated 标记与 sunset 策略