XML example return value is rendered as escaped text, wrapped within <notagname>

[cristalp]

I have an example of an XML document as it would be returned:

  public static final String XML = """
      <foo>
        <bar>baz</bar>
      </foo>""";

This is used within the REST endpoint:

  @APIResponse(responseCode = "200", description = "Bla bla", content = {
      @Content(mediaType = MediaType.APPLICATION_JSON, example = "JSON example"),
      @Content(mediaType = MediaType.APPLICATION_XML, example = XML),
      @Content(mediaType = MediaType.TEXT_PLAIN, example = "Text example") })

In the openapi.yml this is rendered as

            application/xml:
              example: |-
                <foo>
                  <bar>baz</bar>
                </foo>

But in SwaggerUI, I see a strange escaped text:

See also https://github.com/fastapi/fastapi/discussions/8440

[MikeEdgar]

How about something like this?

@XmlRootElement(name = "foo")
static class FooSchema { }

@APIResponse(responseCode = "200", description = "Bla bla", content = {
      @Content(mediaType = MediaType.APPLICATION_JSON, example = "JSON example"),
      @Content(mediaType = MediaType.APPLICATION_XML, example = XML,
               schema = @Schema(implementation = FooSchema.class)),
      @Content(mediaType = MediaType.TEXT_PLAIN, example = "Text example") })

[cristalp]

Thanks, that's a workaround which works. However, it's kind of obscure :-) , so it would be nice if this was generated correctly right out of the box. By this I mean that it's clear from the MediaType that it's XML, so the plugin could generate what's necessary to get it right.

[MikeEdgar]

Right, I agree. It seems to be more an issue with Swagger UI in my opinion. I'd expect it to perhaps be aware of the representation for the XML media type without requiring the schema. I wouldn't have guessed the work-around without the fastapi issue you linked.

[MikeEdgar]

By this I mean that it's clear from the MediaType that it's XML, so the plugin could generate what's necessary to get it right.

Unfortunately, just from the @Content without the schema, there isn't enough information to do it. Generating an empty schema always in such cases would not be good either.

[cristalp]

Too bad... so there's no solution except defining schemas by hand?

[MikeEdgar]

Do you already have a class that represents the XML that includes @XmlRootElement? The @Schema annotation doesn't include a way to specify XML information, but it has been requested in the spec [1]. No one has had a chance to work on that yet, but contributions are always welcome, of course.

[1] https://github.com/microprofile/microprofile-open-api/issues/530

[cristalp]

Thanks for the information. Unfortunately, at the moment I'm not able to take out some time of my schedule. But maybe one day I'll be able to convince my boss :-)

Anyway, since the other feature request already exists, please close this one - and thanks for the workaround!