API 破坏性变更检测与迁移规划器

对比两份 OpenAPI 3.x schema，识别 breaking changes 并给出影响评级与迁移建议

适合 API 团队在发版前识别高风险变更，如删除字段、收紧类型、请求体变必填等。

示例结果

1 个示例

检测 API 版本间的破坏性变更

对比两份 OpenAPI 文档，识别会影响旧客户端的请求或响应收紧变更

Breaking changes are grouped by impact with migration strategies.
查看输入参数
{ "oldSchema": "openapi: 3.0.3\npaths:\n /users:\n post:\n requestBody:\n required: false\n content:\n application/json:\n schema:\n type: object\n properties:\n name: { type: string }\n responses:\n \"200\":\n description: ok\n content:\n application/json:\n schema:\n type: object\n properties:\n id: { type: string }\n name: { type: string }\n", "newSchema": "openapi: 3.0.3\npaths:\n /users:\n post:\n requestBody:\n required: true\n content:\n application/json:\n schema:\n type: object\n required: [name, role]\n properties:\n name: { type: string }\n role: { type: string }\n responses:\n \"200\":\n description: ok\n content:\n application/json:\n schema:\n type: object\n properties:\n id: { type: string }\n" }

关键信息

分类
开发与 Web
输入类型
textarea
输出类型
html
样本覆盖
4
支持 API
Yes

概览

API 破坏性变更检测与迁移规划器是一款专为研发团队设计的 OpenAPI 3.x 差异对比工具。通过输入新旧两份 Schema 文档，它能精准识别出删除字段、类型收紧、新增必填项等可能导致旧版客户端崩溃的高风险变更（Breaking Changes）。工具不仅会输出直观的差异对比，还会自动生成影响评级与具体的迁移建议，帮助团队在 API 发版前规避兼容性风险，保障上下游服务的平稳过渡。

适用场景

  • •API 版本迭代或重构发版前，需要评估对现有客户端的兼容性影响时。
  • •团队进行微服务接口合并或拆分，需排查请求参数和响应结构是否发生破坏性改变时。
  • •编写 API 变更日志（Changelog）并为下游开发者制定接口迁移指南时。

工作原理

  • •在“旧版 OpenAPI Schema”输入框中粘贴当前线上版本的 YAML 或 JSON 格式文档。
  • •在“新版 OpenAPI Schema”输入框中粘贴即将发布的最新版本文档。
  • •工具将解析并对比两份 Schema，深度检测路径、请求体、响应结构及数据类型的变更。
  • •最终生成一份 HTML 报告，按影响程度对破坏性变更进行分类，并提供相应的迁移策略。

使用场景

后端开发团队在合并代码前进行 API 契约测试，拦截不兼容的接口修改。
技术负责人或架构师在发版评审阶段，审查 OpenAPI 规范变更带来的全局影响。
技术文档工程师根据对比报告，快速撰写面向外部开发者的 API 升级指南。

用户案例

1. 识别请求体变更为必填项

后端开发工程师
背景原因
团队在重构用户创建接口时，为了数据完整性，决定强制要求客户端传入角色信息。
解决问题
需要确认将 requestBody 改为必填，并在其中新增必填字段 role 会对旧版客户端造成什么影响。
如何使用
将旧版 `/users` 接口的 Schema 填入旧版输入框，将包含 `required: true` 和 `required: [name, role]` 的新版 Schema 填入新版输入框并执行对比。
效果
工具检测到 requestBody 从非必填变为必填，且新增了必填字段 role，将其标记为高风险破坏性变更，并建议在当前版本保持非必填，在下一个大版本再强制要求。

2. 拦截响应字段删除风险

API 架构师
背景原因
某微服务接口在优化响应体积时，移除了部分被认为“不再使用”的冗余字段。
解决问题
担心下游某些老旧系统仍在依赖这些被删除的字段，导致解析报错或业务逻辑异常。
如何使用
粘贴新旧两份 OpenAPI 文档进行对比，重点关注 responses 对象的差异报告。
效果
报告清晰列出 200 响应体中 name 字段被移除，提示此为严重破坏性变更，建议先使用 `@deprecated` 标记该字段而非直接删除。

用 Samples 测试

development
Postman Collections - API 测试
全面的 Postman collection 示例，包括 API 测试、自动化脚本、环境变量、mock 服务器和 REST API 的高级测试模式
title token api
sample
OpenAI API 示例
全面的OpenAI API示例，包括GPT模型、DALL-E图像生成、Whisper音频处理和函数调用
title token api
sample
WebGPU 图形API
用于浏览器中高性能3D图形和GPU计算的现代图形API
title token api
sample
Truffle 开发套件示例
Truffle 以太坊开发框架示例，包括智能合约、测试、部署、迁移、调试和开发工作流
keywords migration,contract,testing
sample

常见问题

支持哪些版本的 OpenAPI 规范？

目前主要支持 OpenAPI 3.x（包括 3.0 和 3.1）版本的 YAML 或 JSON 格式文档对比。

什么是 API 的破坏性变更（Breaking Change）？

指可能导致现有客户端请求失败或解析错误的变更，例如删除已有响应字段、更改字段数据类型、或将非必填请求参数改为必填。

工具能检测出新增的非必填字段吗？

新增非必填字段通常属于向后兼容的安全变更。工具在对比时会将其识别为新增项，但不会将其标记为破坏性变更，从而让您聚焦于高风险项。

报告中的“影响评级”是如何划分的？

评级基于变更对客户端的破坏程度。例如，删除核心响应字段或新增必填请求参数为高风险；而修改字段描述或增加可选参数则为低风险或无风险。

输入的 Schema 数据会保存在服务器上吗？

不会。所有的 Schema 解析和对比处理均在安全的临时环境中完成，不会持久化存储您的 API 文档数据。

API 文档

请求端点

POST /zh/api/tools/api-breaking-changes-detector-migration-planner

请求参数

参数名 类型 必填 描述
oldSchema textarea 否 -
newSchema textarea 否 -

响应格式

{
  "result": "
Processed HTML content
",
  "error": "Error message (optional)",
  "message": "Notification message (optional)",
  "metadata": {
    "key": "value"
  }
}
HTML: HTML

AI MCP 文档

将此工具添加到您的 MCP 服务器配置中： 

{
  "mcpServers": {
    "elysiatools-api-breaking-changes-detector-migration-planner": {
      "name": "api-breaking-changes-detector-migration-planner",
      "description": "对比两份 OpenAPI 3.x schema，识别 breaking changes 并给出影响评级与迁移建议",
      "baseUrl": "https://elysiatools.com/mcp/sse?toolId=api-breaking-changes-detector-migration-planner",
      "command": "",
      "args": [],
      "env": {},
      "isActive": true,
      "type": "sse"
    }
  }
}

你可以串联多个工具，比如：`https://elysiatools.com/mcp/sse?toolId=png-to-webp,jpg-to-webp,gif-to-webp`，最多20个。

如果遇见问题，请联系我们：[email protected]