如何在 OpenAPI (Swagger) 中指定默认的 XML 元素文本？答案

【问题标题】：How to specify the default XML element text in OpenAPI (Swagger)?如何在 OpenAPI (Swagger) 中指定默认的 XML 元素文本？
【发布时间】：2019-01-12 23:52:00
【问题描述】：

我正在为以下 XML 有效负载构建 OpenAPI (Swagger) 2.0 定义，以便在 Swagger UI 中使用：

<addressElement>
    <key type="RECORD_ID" item="3">Enter value here</key>
</addressElement>

我在弄清楚如何为元素 key 显示默认值“在此处输入值”时遇到问题。将这个默认值放在 OpenAPI 定义中的什么位置？我的定义是这样的：

    "definitions": {
     "addressElement": {
      "type": "object",
      "title": "Address Element",
      "properties": {
        "key": {
          "type": "object",
          "properties": {
          "type":{
            "type": "string",
            "example": "RECORD_ID",
            "xml":{
              "attribute": true
            }
          },
          "item":{
            "type": "integer",
            "format": "int64",
            "example": "3",
            "xml":{
              "attribute": true
            }
          }
        }
      },
    },
    "xml": {
      "name": "addressElement"
    }
  }
 }

【问题讨论】：

Swagger XML attribute and content definition的可能重复

标签： swagger swagger-2.0 openapi

【解决方案1】：

目前这是不可能的，因为 OpenAPI 没有办法用属性来表示 XML 元素，例如

<key type="RECORD_ID" item="3">Enter value here</key>

只能为对象定义属性

<obj attr="value">
  <elem>Some text</elem>
</obj>

但不适用于简单的<elem>text</elem> 元素。

这里有一个关于此限制的未解决问题：
How to represent XML elements with attributes

也就是说，OpenAPI 规范维护人员正在考虑使用alternative data modeling schemas（例如 XSD Schema）的选项，因此您的用例可能会在 OpenAPI 的未来版本中得到支持。

【讨论】：