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

user_9539931 0
Viewed 919

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"
    }
  }
 }
swagger-2.0 swagger openapi
1 Answers

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.

user_1131160
Related