Howto define an unwrapped XML response with OpenAPI

Question

I want to write a RESTful webserver which serves the following XML document:

<Services>
<TileMapService title="TMS server" version="1.0.0" href="/tms/1.0.0"/>
<TileMapService title="TMS server" version="1.0.1" href="/tms/1.0.1"/>
</Services>

I use the OpenAPI Generator Gradle Plugin to generate model classes for my SpringBoot RestController.

openApiGenerate {
  generatorName = "spring"
  ...
  configOptions = [
    withXml: "true",
    ...
  ]
}

with the following openapi.yaml spec file:

...
"paths" : {
  "/tms" : {
    "get" : {
      "operationId" : "getServices",
      "responses" : {
        "200" : {
          "content" : {
            "text/xml" : {
              "schema" : {
                "$ref" : "#/components/schemas/ServicesRoot"
              }
            }
          }
        }
      }
    }
  }
},
"components" : {
    "schemas" : {
      "ServicesRoot" : {
        "xml" : {
          "name" : "Services"
        },
        "properties" : {
          "TileMapServices" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/TileMapService"
            }
          }
        }
      },
      "TileMapService" : {
        "xml" : {
          "name" : "TileMapService"
        },
        "properties" : {
          "title" : {
            "type" : "string",
            "xml" : {
              "attribute" : true
            }
          },
          "version" : {
            "type" : "string",
            "xml" : {
              "attribute" : true
            }
          },
          "href" : {
            "type" : "string",
            "xml" : {
              "attribute" : true
            }
          }
        }
      },
...

The generator creates a ServicesRoot model class from this spec. When I use this model with my RestController to create a response I get:

<Services>
  <TileMapServices>
    <TileMapServices title="TMS server" version="1.0.0" href="/tms/1.0.0"/>
    <TileMapServices title="TMS server" version="1.0.1" href="/tms/1.0.1"/>
  </TileMapServices>
</Services>

Can you please help me to solve the following problems:

The TileMapService array items are wrapped inside a <TileMapServices> XML-element. I need the array items "unwrapped" within the </Services> parent XML-element.
The array items XML-Element name is "pluralized" as <TileMapServices .../> with a trailing "s".

I want to use the generated model class as response object for the RestController and with Jackson XMLMapper to serialize XML documents.

This is what I need:

<Services>
  <TileMapService title="TMS server" version="1.0.0" href="/tms/1.0.0"/>
  <TileMapService title="TMS server" version="1.0.1" href="/tms/1.0.1"/>
</Services>

Randy · Accepted Answer · 2024-01-16 16:53:10Z

0

So your service is returning JSON. My answer assumes Java and Spring Boot based on you using Gradle and a generator.
To get XML, have a look at this: Spring-boot return json and xml from controllers

It shows the Maven/Gradle dependency to add to the project for XML output and related configuration.

To "adjust" the marshalling, you need to use something like

@JacksonXmlElementWrapper(useWrapping = false)

or

@JsonProperty("X")

For some guidance on that see: https://www.baeldung.com/jackson-xml-serialization-and-deserialization.

You may need to create a specific DTO to return rather than an internal model to more directly control marshalling with the above annotations.

~~Hopefully, this gets you started.~~

My appologies. I misread your post.

Did you see this post:

How to define an array of objects in OpenAPI 3.0?

In it, they use 'unwrapped'.

components:        
  schemas:
    abc:
      xml:
        wrapped : true    <<--- here!  set to false?
        name: abc
      type: array
      items:
        type: object
        xml:
          name: 'item'
        properties: 
          Name:
            type: string
          age:
            type: integer
          enabled: 
            type: boolean
      example:
        - Name: no1
          age: 18
          enabled: true
        - Name: no2
          age: 20
          enabled: false

edited Jan 16, 2024 at 16:53

answered Jan 12, 2024 at 16:42

Randy

8299 silver badges14 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

G. Fiedler Over a year ago

The service is returning XML. I cannot edit the DTO because it is generated from an openapi.yaml spec file and will be overwritten by the generator. I am looking for a generator config or spec file syntax which generates the DTO so that the RestController generates the correct XML document with it.

Collectives™ on Stack Overflow

Howto define an unwrapped XML response with OpenAPI

1 Answer 1

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related