dsh-api-contract

Readme

# 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 requests`）。

## 安装

```bash
dsh plugin add github:uckkk/dsh-api-contract
```

> 安装即在本机运行第三方代码，请自行审阅源码。

## 安装

```bash
dsh plugin add github:uckkk/dsh-api-contract
```

## 使用

安装后在会话中调用该插件注册的工具即可。

## 许可

MIT

> 安装即在本机运行第三方代码，请自行审阅源码。