dsh-api-contract

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

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

提供的工具

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

安装

bash
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 req