如何修改Swagger文件捕获API响应中driver节点的id属性？

API响应格式（XML） #

<drivers>
 <driver id="103721">
  <reported_driver_id>5555</reported_driver_id>
  <display_ref>5555</display_ref>
  <name>Toronto Training 1</name>
  </driver>
</drivers>

注：响应包含数千条driver数据。

当前Swagger定义 #

"definitions" : {
"sg_response##drivers##driver" : {
  "properties" : {
    "id" : {
      "type" : "number"
    },
    "reported_driver_id" : {
      "type" : "number"
    },
    "display_ref" : {
      "type" : "number"
    },
    "name" : {
      "type" : "string"
    }
  }
}

ETL输出问题 #

当前ETL结果中无法捕获driver节点的id属性，示例输出：

"id","reported_driver_id","display_ref","name"
 ,"5555","5555","Toronto Training 1"
 ,"6666","6666","Toronto Training 2"
 ,"6161","6161","Billings Demo 4"
 ,"169168","169168","Dharminder Grewal"

解决方案 #

方法1：修改Swagger定义以支持XML属性捕获 #

OpenAPI（Swagger）支持通过xml扩展标记XML元素的属性。你需要在id字段的定义中添加xml配置，指定它对应XML节点的属性：

"definitions" : {
  "sg_response##drivers##driver" : {
    "properties" : {
      "id" : {
        "type" : "number",
        "xml": {
          "attribute": true
        }
      },
      "reported_driver_id" : {
        "type" : "number"
      },
      "display_ref" : {
        "type" : "number"
      },
      "name" : {
        "type" : "string"
      }
    },
    "xml": {
      "name": "driver"
    }
  },
  "sg_response##drivers": {
    "type": "array",
    "items": {
      "$ref": "#/definitions/sg_response##drivers##driver"
    },
    "xml": {
      "name": "drivers",
      "wrapped": true
    }
  }
}

关键修改点：

• 在id字段添加"xml": {"attribute": true}，明确该字段对应XML节点的属性
• 给driver定义添加"xml": {"name": "driver"}，映射到XML中的<driver>元素
• 补充drivers数组定义，确保整个XML结构被正确解析

如果你的ETL工具支持OpenAPI的XML扩展规范，修改后应该能正常捕获到id属性。

方法2：推动后端调整API结构 #

如果ETL工具不支持OpenAPI的XML扩展，或者无法通过Swagger配置解决，就需要后端团队调整API响应格式，将id从节点属性改为子节点，比如：

<driver>
  <id>103721</id>
  <reported_driver_id>5555</reported_driver_id>
  ...
</driver>

这种结构无需额外配置，就能被现有Swagger定义正确捕获。

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