pb33f/openapi-changes
GitHub: pb33f/openapi-changes
一款专注于 OpenAPI 规范变更检测的命令行工具，能够智能识别版本间的破坏性修改，帮助团队在 API 发布前确保向后兼容性。
Stars: 333 | Forks: 28
[](https://discord.gg/x7VACVuEGP)
[](https://github.com/pb33f/wiretap/releases)
[](https://www.npmjs.com/package/@pb33f/openapi-changes)
[](https://hub.docker.com/r/pb33f/openapi-changes)
# OpenAPI 变更
## 世界上**最性感**的 OpenAPI diff 工具。
我们马上就会谈到“性感”的部分，但简而言之，`openapi-changes` 允许你
查看和探索你的 OpenAPI Specification 发生了哪些变化，无论是单次变更，
还是完整的历史记录！
使用终端或浏览器探索 OpenAPI 变更历史，你可以选择最适合自己的体验。非常适合
个人使用，或用于 CI/CD 流水线自动化。
## 它为何是“最性感”的？
你见过像这样的 OpenAPI diff 报告吗？
那能够实现同样功能的终端 UI 呢？
## 文档
### 👉 [⚡ 在线试用 Demo ⚡](https://pb33f.io/openapi-changes/demo/) 👈
### [快速入门指南 🚀](https://pb33f.io/openapi-changes/quickstart/)
请在 https://pb33f.io/openapi-changes/ 查看所有文档
- [安装 openapi-changes](https://pb33f.io/openapi-changes/installing/)
- [配置 Breaking Changes](https://pb33f.io/openapi-changes/configuring/)
- [命令参数](https://pb33f.io/openapi-changes/command-arguments/)
- CLI 命令
- [`console` 命令](https://pb33f.io/openapi-changes/console/)
- [`html-report` 命令](https://pb33f.io/openapi-changes/html-report/)
- [`report` 命令](https://pb33f.io/openapi-changes/report/)
- [`summary` 命令](https://pb33f.io/openapi-changes/summary/)
- [关于 openapi-changes](https://pb33f.io/openapi-changes/about/)
准备好尝试了吗？
## 使用 Homebrew Tap 安装
```
brew install pb33f/taps/openapi-changes
```
## 使用 npm 或 yarn 安装
```
npm i -g @pb33f/openapi-changes
```
如果你倾向于使用 yarn _（推荐）_
```
yarn global add @pb33f/openapi-changes
```
## 使用 cURL 安装
```
curl -fsSL https://pb33f.io/openapi-changes/install.sh | sh
```
## 使用 Docker 安装/运行
```
docker pull pb33f/openapi-changes
```
Docker 镜像支持 `linux/amd64` 和 `linux/arm64` 架构。
运行时，将当前工作目录挂载到容器中，如下所示：
```
docker run --rm -v $PWD:/work:rw pb33f/openapi-changes summary . sample-specs/petstorev3.json
```
## 自定义 Breaking Changes 规则配置
openapi-changes 使用 [libopenapi](https://github.com/pb33f/libopenapi) 的可配置 breaking change
检测系统。你可以通过提供配置文件来自定义哪些变更被视为“breaking”。
### 使用配置文件
```
# 使用显式配置文件
openapi-changes summary -c my-rules.yaml old.yaml new.yaml
# 或将 changes-rules.yaml 放置在当前目录（自动检测）
openapi-changes summary old.yaml new.yaml
```
### 默认配置位置
openapi-changes 会搜索 `changes-rules.yaml`：
1. 当前工作目录 (`./changes-rules.yaml`)
2. 用户配置目录 (`~/.config/changes-rules.yaml`)
### 配置示例
创建一个 `changes-rules.yaml` 文件：
```
# 自定义破坏性规则配置
# 仅指定覆盖项 - 未指定的规则使用默认值
# 将操作移除设为非破坏性（用于弃用工作流）
pathItem:
get:
removed: false
post:
removed: false
put:
removed: false
delete:
removed: false
# 将枚举值移除设为非破坏性
schema:
enum:
removed: false
# 将参数变更设为非破坏性
parameter:
required:
modified: false
```
### 配置结构
每个规则有三个选项：
- `added`: 添加此属性是否为 breaking change？ (true/false)
- `modified`: 修改此属性是否为 breaking change？ (true/false)
- `removed`: 删除此属性是否为 breaking change？ (true/false)
### 可用组件
你可以为这些 OpenAPI 组件配置规则：
| Component | Description |
|-----------------------|----------------------------------------------------|
| `paths` | 路径定义 |
| `pathItem` | Operations (get, post, put, delete, etc.) |
| `operation` | Operation 详情 (operationId, requestBody, etc.) |
| `parameter` | 参数属性 (name, required, schema) |
| `schema` | Schema 属性 (type, format, enum, properties) |
| `response` | 响应定义 |
| `securityScheme` | 安全方案属性 |
| `securityRequirement` | 安全要求 |
有关可配置属性的完整列表和更多示例，请参阅
[完整配置文档](https://pb33f.io/openapi-changes/configuring/)。
请访问 https://pb33f.io/openapi-changes/ 查看所有文档
标签：API兼容性, API差异比对, API文档, API版本管理, API规范, DNS解析, EVTX分析, Go语言, HTML报告, JSON, LNA, OpenAPI, SOC Prime, Swagger, TUI, TypeScript, YAML, 前端框架, 安全可观测性, 安全库, 安全插件, 开发工具, 开源项目, 日志审计, 版本控制, 破坏性变更检测, 程序破解, 请求拦截