swagger-uiopenapi

I am having difficulty specifying an XML example for a response in OpenAPI 3


I have a JSON file for OpenAPI 3 that contains the following:

            "trait_hasProjectResponse_200": {
                "description": "",
                "content": {
                    "application/xml": {
                        "example": {
                            "value" : "<project><foo>1</foo><bar>2</bar></project>"
                        }
                    }
                }
            },

This results in the following display on the current swagger-ui:

enter image description here

How do I specify an example of XML for a parameter or response in the OpenAPI 3 spec? I have looked through the documentation and it seems to be targest mostly at JSON. What do I need to do the my output that is generating the OpenAPI 3 JSON file.

I have also tried to use the externalValue and have has similar difficulties.


Solution

  • Remove the value key from the example (value is only used with multiple examples).

    "example": "<project><foo>1</foo><bar>2</bar></project>"
    


    Alternatively, you can define a schema for the response, and Swagger UI will generate examples based on the schema. In your example, the schema is a project object that contains the foo array. You can specify [1, 2] as the example values for the foo array:

      "components": {
        "responses": {
          "trait_hasProjectResponse_200": {
            "description": "",
            "content": {
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/project"
                }
              }
            }
          }
        },
        "schemas": {
          "project": {
            "type": "object",
            "properties": {
              "foo": {
                "type": "array",
                "items": {
                  "type": "integer"
                },
                "xml": {
                  "wrapped": false
                },
                "example": [1, 2]
              }
            }
          }
        }
      }
    

    This will give you:

    XML response example generated by Swagger UI based on the response schema