Swagger-ui: xml example cannot be generated for response type of array

[borcherspm]

Q&A (please complete the following information)

• OS: Windows 10
• Browser: Firefox, Chrome, Edge
• Method of installation: npm
• Swagger-UI version: 3.11.0
• Swagger/OpenAPI version: Swagger 2.0

Content & configuration

I've reproduced this locally, but even easier to demonstrate, petstore has the same issue.

Example Swagger/OpenAPI definition:
https://generator.swagger.io/api/swagger.json

snippet from swagger.json

      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Pet"

Describe the bug you're encountering

In swagger ui, when you have a GET that has a response that is a list, and you selected content type of xml, the Example Value has an error "XML example cannot be generated".

To reproduce...

Steps to reproduce the behavior:

1. Go to https://editor.swagger.io
2. Expand /pet/findByStatus
3. Make sure Response content type is application/xml
4. Example Value for status code 200 has "XML example cannot be generated"

Expected behavior

I would expect to see the example xml for the response.

Screenshots

[Mic75]

Hello @shockey , any ETA on a fix regarding this issue?

[euroform-pa]

@shockey We're facing issue with XML sample generation in case of collection is part of response object. Kindly let us know about ETA on a fix.

[euroform-pa]

Added the demo project to reproduce the issue with Swashbuckle for Xml sample generation issue. Demo project
Kindly suggest the solution to view correct Xml sample generation.

[euroform-pa]

Added the demo project to reproduce the issue with Swashbuckle for Xml sample generation issue. Demo project
Kindly suggest the solution to view correct Xml sample generation.

Any update on this?

[wambling]

Any workaround solution for this?

[NickNiebling]

I think this might be related to older issue:
XML Example for Arrays does not display #3132

Above issue does speak to at least some issue with Swashbuckle OpenAPI generation:

Yes we are but its an issue with Swashbuckle not generating the appropriate swagger doc info; once i add that information in, the UI renders fine ... the Petstore example is also broken in the same way and needs to be amended to include the xml.name/wrapped elements

Re. workaround, there is more information in above issue:

I just realized a single-item example is actually correct. To have array items wrapped into an extra tag, the array schema must have xml.wrapped=true.

Another issue ´seems to be related as well:
XML example cannot be generated with 'allOf' #4423

This has been an issue for a while, but apparently not a priority to fix (I assume collaborators are all using json or don't mind too much about XML examples).

[Kevweir]

I'm using NuGet Package Swashbuckle.AspNetCore 5.0.0-rc4 and this is still an Issue on November 12, 2019

[Kevweir]

When you generate the schema for response type 200 for app/ToDoItems/1 we get the following schema for responses:

"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TodoItem"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/TodoItem"
}
}
}
},

When you generate the schema for response type 200 for app/ToDoItems we get the following schema for responses:

"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TodoItem"
}
}
},
"application/xml": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TodoItem"
}
}
}
}
},

Its this second scenario that is producing the error "XML example cannot be generated; root element name is undefined" in the Swagger UI.

[calife]

You can use something like this to wrap

    responses:
      '200':
        description: Success
        content:

          'application/xml':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SDDLItem'
              xml:
                name: response

components:
schemas:

SDDLItem:
  type: object
  xml:
    name: SDDLItem

[whateverxforever]

Did anyone figure out a workaround for this issue or does this issue still exist?

[whateverxforever]

You can use something like this to wrap

    responses:
      '200':
        description: Success
        content:

          'application/xml':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SDDLItem'
              xml:
                name: response

components:
schemas:

SDDLItem:
  type: object
  xml:
    name: SDDLItem  

This is not working due to some reason.

[fdcds]

Did anyone figure out a workaround for this issue or does this issue still exist?

Providing any schema: xml: name: ... did the trick for me. The value is ignored (because schema: xml: wrapped: true is not set), but at least the example is rendered fine.

[Sslimon]

Hi all

Are there some updates about this? I think I have a similar problem:

I have a Spring Boot Rest Api and I want to have the swagger documentation. Mostly the Api produces application/xml. When the return class is annotated with XmlRootElement and the properties have the XmlElement attributes everything is working fine. But if a primitive type or a List is returned, the root element is missing. Is it somehow possible to tell springdoc he should use jaxb to generate all this information/names. So that the xml has the root name and everything which then really gets returned?

Thank you very much and best
Simon

[whateverxforever]

I found a work-around for this
https://app.swaggerhub.com/apis/whateverxforever/SampleApi/v1-oas3

 get:
      summary: List of all orders
      operationId: getOrderList
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
            application/xml:
              schema:
                type: object
                xml:
                  name: Data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'

I hope this helped! 😉

[Sslimon]

@whateverxforever Thanks for you response :)

This would work, yes. But I use springdoc openapi which generates the swagger json file for me. When I annotate my models with @XmlRootElement and @XmlElement the generated schema: xml: is written correctly.

For example like this:

@XmlRootElement
public class Employee {
    @XmlElement
    private Address address;
}

@XmlRootElement
public class Address {
}

But if the return type of an endpoint is a primitive data type like boolean or a List than the schema: xml: is completely missing.

I could add them manually, but the project is quite big.
Or I could write wrapper classes, but I should not change the code.

My idea then was if swagger could use jaxb to create this xml informations. Like this, the xml names would be exactly the same as the rest endpoint returns.

Do you know more or less what i mean :)

[whateverxforever]

Hello @Sslimon,

I faced the same issue while generating docs using Stoplight for my project. Stoplight was generating the doc fine for JSON data but for XML I had to manually go at each end point and write the code myself. I know it's not what you wanted to hear 😓, but I think this is a common issue in swagger. Sorry couldn't be of any more help.

[Sslimon]

Okay, too bad. I was hoping that somebody maybe knows a workaround, but then I can't avoid to adapt it myself :) The JSON is also correct, only the xml stuff is sometime wrong/not complete. But thank you very much for your answers and help!