dsh-api-contract · 接口契约助手

解析 OpenAPI 3.x（JSON 或 YAML），生成 TypeScript / Python 类型化客户端，并检测两个规范版本之间的破坏性变更。纯 Node 实现，无网络、无外部服务。

提供的工具

工具	作用
gen_client	解析规范，生成类型化客户端（TS 基于 fetch / Python 基于 requests）
diff_spec	对比旧版/新版规范，列出破坏性变更与非破坏性变更

安装

dsh plugin add dsh-api-contract

安装后在 profile 的 package.json 的 dsh.profile.bundles 中加入 "dsh-api-contract"。

用法示例

根据 openapi.yaml 生成一个 TypeScript 客户端
→ 调用 gen_client(spec="openapi.yaml", lang="typescript", outDir="./src/api")

升级接口前看看有没有破坏性变更
→ 调用 diff_spec(oldSpec="openapi.v1.json", newSpec="openapi.v2.json")

破坏性变更检测项

• 删除接口路径、删除方法
• 删除必填参数、参数类型变化
• 移除 2xx 响应、响应结构变化

说明

• 支持 JSON 与常见块结构 YAML（嵌套映射、序列、$ref、内联 []/{}、字面量块 |）。
• Python 客户端依赖 requests（pip install requests）。