OpenAPI 契约测试引擎
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_92725383/api-contract-tester-pro。
技能介绍
解决什么问题
当团队同时维护多份 API 规范时,很容易出现这类问题:v2 版本的接口被悄悄删除,客户端按旧文档调用直接 404;某个响应字段被移除,前端解析时突然报 undefined;枚举值范围缩小,老客户端传入合法值却被拒绝。手工编写契约测试既费时又容易遗漏边界场景,版本间的破坏性变更往往要等集成失败后才发现。
核心能力与工作流程
该引擎以 Python 纯标准库实现,核心流程分为四步:
- 规范解析:
OpenAPIParser支持 OpenAPI v2/v3 双版本,能够解析$ref引用,并处理allOf/oneOf/anyOf组合关键字,最终转换为APIEndpoint和SchemaObject结构。 - 契约测试生成:
ContractTestGenerator针对每个端点自动生成正向、负向、边界和 Schema 校验四类测试用例,覆盖必填字段、类型错误、空值、越界等典型场景。 - 破坏性变更检测:
BreakingChangeDetector对比不同版本规范时,会输出六类变更:path_removed、response_removed、type_changed、required_field_added、enum_narrowed、property_removed,均标记为 HIGH 严重级别,帮助你在发布前拦截潜在问题。 - Mock 响应生成:
MockResponseGenerator基于 Schema 约束生成类型感知的示例响应,包含格式特定的默认值,便于前端联调。
适用边界
工具仅聚焦 OpenAPI 契约层,不涉及接口性能、安全或业务逻辑测试。YAML 格式解析需可选依赖 pyyaml,若规范中大量使用自定义扩展关键字,可能无法完全覆盖。破坏性变更判定规则较保守,无法识别逻辑层面的破坏(如默认值语义改变),建议结合集成测试共同使用。
使用场景
- 维护多版本 API 规范,每次迭代前对比新旧版本,排查端点被删、字段被移除等破坏性变更。
- 接口开发初期写好 OpenAPI 文档,需要自动生成正向、负向、边界测试用例用于验证服务端实现。
- 前后端并行开发,后端按 Schema 生成类型一致的 Mock 响应,供前端先跑通页面与交互。
- 接手遗留 Swagger v2 文档 ,要将其迁移到 OpenAPI v3 并确认路径、参数与响应结构保持一致。
适合人员
- 负责多个微服务 API 版本迭代、需要守住兼容性契约的后端工程师。
- 在接口交付前编写和维护契约测试、关注 Schema 校验覆盖度的技术测试工程师。
- 需要按 OpenAPI 文档先搭页面、依赖 Mock 响应推进工作流的前端工程师。
- 维护公司 API 网关规范、定期审计各团队 OpenAPI 文档一致性的技术规范负责人。