How to specify the default XML element text in OpenAPI (Swagger)?

问题

I'm building an OpenAPI (Swagger) 2.0 definition for the following XML payload to use within the Swagger UI:

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

I'm having an issue figuring out how to display the default value 'Enter value here' for the element key. Where would one place this default value in an OpenAPI definition? My definition looks like this:

    "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"
    }
  }
 }

回答1:

This is currently not possible because OpenAPI does not have a way to represent XML elements with attributes such as

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

Attributes can only be defined for objects

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

but not for simple <elem>text</elem> elements.

There's an open issue about this limitation here:
How to represent XML elements with attributes

That said, OpenAPI Specification maintainers are considering an option to use alternative data modeling schemas (such as XSD Schema), so your use case might be supported in a future version of OpenAPI.

来源：https://stackoverflow.com/questions/54164941/how-to-specify-the-default-xml-element-text-in-openapi-swagger

标签

swagger

swagger-2.0

openapi