OpenAPI 升级前后怎么对比：从新增字段到复核清单

开始之前

API 发布审查需要一份可信的基线。本例只给响应增加一个可选字段，帮助你区分“工具报告了变化”和“已证实会破坏客户端”。不会访问或修改真实接口。

固定旧版基线

从上一个已发布版本取文档。本例把下面内容放入左侧“旧版 OpenAPI”，不要把当前开发分支误当成旧版。

示例

{
  "openapi": "3.0.3",
  "info": {
    "title": "订单查询示例",
    "version": "1.0.0"
  },
  "paths": {
    "/orders/{id}": {
      "get": {
        "operationId": "getOrder",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

准备新版文档

将下面内容放入右侧“新版 OpenAPI”。与旧版相比，只调整文档版本并新增可选的 created_at 响应字段。

示例

{
  "openapi": "3.0.3",
  "info": {
    "title": "订单查询示例",
    "version": "1.1.0"
  },
  "paths": {
    "/orders/{id}": {
      "get": {
        "operationId": "getOrder",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

按变化路径审查

点击“开始分析”。预期包含 created_at 的“字段新增”信息，以及操作定义变化的 review 提示；本例不应出现 risk。review 仍需阅读，不等于已确定不兼容。

保留审查证据

记录两个文档版本、变更路径和消费者验证结果，再下载报告。把左右两侧换成相同旧版文档重试，预期 changes 为空；这个对照能排除误放输入。

新增字段为什么仍需复核

工具将新增响应字段列为信息，但有些客户端会拒绝未知字段，或对响应进行严格快照比较。应使用真实客户端及其解码配置验证；本工具没有运行这些消费者。

比较结果的边界

复杂组合 Schema、鉴权、响应头、默认值和未覆盖的约束可能只给人工复核提示。外部引用不会被抓取。报告没有 risk 不能代替联调或上线验收。

规范依据与检查范围

以 OpenAPI 3.0 / 3.1 为输入。工具在浏览器本地执行基础结构检查，不调用实际 API，不自动获取外部引用，也不替代完整规范校验、鉴权测试或消费者契约测试。

要点总结

左旧右新，先确认基线。
信息提示也需要结合消费者行为判断。
相同文档对照可以帮助排除操作失误。