OpenAPI多属性引用同一对象时API网关Models生成异常问题

问题现象 #

你给出的OpenAPI定义中，coordinates和directions两个属性同时引用#/definitions/TestObject2时，API网关Models列表未生成对应模型，日志中可见coordinates的$ref被错误指向同层级directions的内联Schema，而非公共定义的TestObject2。

# 原定义片段
definitions:   
   TestObject2:
        type: object
        properties:
          key1:
            type: string
   TestObject:
        type: object
        properties:
          name:
            type: string
          city:
            type: string
          coordinates:
            $ref: '#/definitions/TestObject2'
          directions:
            $ref: '#/definitions/TestObject2'

排查步骤 #

• 第一步：校验OpenAPI语法规范性
  1. 确认YAML文件无缩进错误、无空格和Tab混用问题，可使用swagger-cli validate <定义文件路径>命令本地执行语法校验
  2. 确认引用路径的大小写、节点层级和definitions中的定义完全匹配，部分解析器对大小写敏感
• 第二步：验证网关解析器去重逻辑缺陷
  你遇到的错误核心是网关的OpenAPI解析器存在bug：解析时会将首次遇到的TestObject2内联到directions属性，后续遇到相同引用时错误指向已内联的同文档节点，而非保留公共定义引用。
  验证方法：复制TestObject2重命名为TestObject3，两个属性分别引用两个不同定义，若此时Models列表正常生成两个模型、引用指向正确，即可确诊为解析器重复引用处理bug。
• 第三步：检查网关模型生成配置
  1. 关闭网关的「小Schema自动内联」优化开关：部分网关默认会将属性少于指定数量的公共定义直接内联到引用处，不生成独立Model，关闭该开关即可保留公共$ref指向
  2. 升级API网关到最新稳定版本：低版本网关普遍存在多引用同一Schema的处理bug，官方通常会在高版本修复该类问题

临时绕过方案 #

若暂时无法升级网关或修改配置，可使用以下方案规避问题：

1. 给TestObject2添加一个无业务意义的可选属性，改变Schema哈希值规避错误去重逻辑：

TestObject2:
  type: object
  properties:
    key1:
      type: string
    dummy: # 新增可选冗余字段
      type: string
      default: ""

2. 使用allOf包裹$ref，避免被解析器错误内联：

coordinates:
  allOf:
    - $ref: '#/definitions/TestObject2'
directions:
  allOf:
    - $ref: '#/definitions/TestObject2'

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