OpenAPI: combine JAXB and JSON (WRAPPER_OBJECT) correctly?

OpenAPI: combine JAXB and JSON (WRAPPER_OBJECT) correctly?

Dear community,

I’m a beginner with swagger/openapi. I want write Java classes with annotations and generate
documentation by OpenAPI library.

In my gradle project I use:

implementation "io.swagger.core.v3:swagger-core:2.2.2"
implementation 'io.swagger.core.v3:swagger-annotations:2.2.2'
implementation "io.swagger.core.v3:swagger-jaxrs2:2.2.2"
implementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.13.2'
implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.13.2'
implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.13.2'

My demo class is:

@XmlRootElement(name = "Cat")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(propOrder = { "id", "name" })
@JsonTypeName("Cat")
@JsonTypeInfo(include = As.WRAPPER_OBJECT, use = Id.NAME)
public class Cat {
    private final String id;
    private final String name;


    public Cat(String id, String name) {
          this.id = id;
          this.name = name;
    }

    public Cat() {   // Just for JAXB and demo
        this("n/a", "n/a");
    }
    // Getters
}

Serializing a object Cat cat = new Cat("01", "Kitty"); with JAVA works fine (as expected).

JSON: (it is wrapped, as requested by As.WRAPPER_OBJECT)

{"Cat":{"id":"01","name":"Kitty"}}

XML:

<Cat><id>01</id><name>Kitty</name></Cat>

My service class is:

@OpenAPIDefinition(info = @Info(title = "CatSwagger", description = "MyDescr01", version = "1.2"))
@Path("/public/v1")
public interface CatService {
    @Operation(summary = "getCat", description = "OpDescr")
    @GET
    @Path("/cat")
    @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
    public Cat getCat();
}

The problem:
The generated YAML file, uploaded to swagger editor.

  • I see a correct JSON representation (fine and wrapped)
  • I can’t see the XML representation (broken).
    • ->XML example cannot be generated; root element name is undefined

For me it looks, the JSON/WRAP instruction will break the XML definition.

YAML:

openapi: 3.0.1
info:
  title: MySwagger01
  description: MyDescr01
  version: "1.2"
paths:
  /public/v1/cat:
    get:
      summary: getCat
      description: OpDescr
      operationId: getCat
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                type: object
                properties:
                  Cat:
                    $ref: '#/components/schemas/Cat'
            application/xml:
              schema:
                type: object
                properties:
                  Cat:
                    $ref: '#/components/schemas/Cat'
components:
  schemas:
    Cat:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      xml:
        name: Cat

I found, if I remove the object definition for operation /public/v1/cat from the XML defintion,
just have a reference:

            application/xml:
              schema:
                type: object
                properties:
                  Cat:
                    $ref: '#/components/schemas/Cat'

to

            application/xml:
              schema:
                    $ref: '#/components/schemas/Cat'

So swagger editor will show my documentation as expected. JSON and XML are looking fine.

Is there any way to control the YAML generation by swagger annotation and fix my problem?

Thanks in advance

Uwe

Read more here: Source link