如何配置OASDiff忽略JSON Schema循环依赖错误并生成API差异报告？

1. 使用OASDiff的跳过验证参数 #

OASDiff提供了跳过Schema验证的命令行参数，可以绕过循环引用的检查。执行diff时添加--skip-validation选项：

oasdiff diff base.json revision.json --skip-validation

这个参数会跳过对OpenAPI规范的严格验证，包括循环引用的检测，让工具能正常加载Schema并生成变更报告。

2. 预处理Swagger Schema（临时修改） #

如果--skip-validation参数无效，你可以临时修改Schema文件，移除循环引用的部分，生成一个临时副本用于diff操作：

• 找到循环引用的节点（比如FilterCriteria中引用自身的字段），将其替换为一个简单的类型定义，例如：

  "FilterCriteria": {
    "type": "object",
    "properties": {
      // 把原来的"$ref": "#/definitions/FilterCriteria"替换为
      "childCriteria": {"type": "object"}
    }
  }
  

• 用修改后的临时文件运行OASDiff，完成diff后丢弃临时文件即可。这种方法会损失循环引用部分的变更检测，但能保证其他API部分的变更正常生成报告。

3. 尝试替代API Diff工具 #

如果上述方法都无效，可以试试其他对循环引用兼容性更好的工具：

• swagger-diff：支持Swagger 2.0的diff对比，对循环引用的处理更宽松
• openapi-diff：针对OpenAPI 3.x的工具，部分版本能自动处理简单循环引用

内容的提问来源于stack exchange，提问作者Darshil Shah