springdoc-openapi、swagger UI 中的 XML 示例

Question

I'm struggling with generation of correct XML examples in springdoc-openapi library.

Controller:

@RestController
@RequestMapping(produces = { MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE })
public class MyController {
    @GetMapping
    public MonetaryValue getMonetaryValue() {
        return new MonetaryValue(BigDecimal.ONE, "EUR");
    }
}

Model

@Schema(name="price", description = "Monetary value")
@JacksonXmlRootElement(localName = "price")
public class MonetaryValue {
    @Schema(example = "EUR")
    @JsonProperty("cur")
    @JacksonXmlProperty(localName = "cur", isAttribute = true)
    private String currency;
    
    @Schema(example = "1.00")
    @JsonProperty("val")
    @JacksonXmlText
    private BigDecimal value;
    
    // getters, setter ...
}

End point called with header Accept: application/xml returns expected result:

<price cur="EUR">1</price>

However it seems that Jackson annotations are ignored in springdoc. Example shown in swagger-ui shows:

<value>
    <cur>EUR</cur>
    <val>1</val>
</value>

I have also tried to add JAXB annotations.

@Schema(name="price", description = "Monetary value")
@JacksonXmlRootElement(localName = "price")
public class MonetaryValue {
        @Schema(example = "EUR")
    @JsonProperty("cur")
    @JacksonXmlProperty(localName = "cur", isAttribute = true)
    @XmlAttribute(name = "cur")
    private String currency;
    
    @Schema(example = "1.00")
    @JsonProperty("val")
    @JacksonXmlText
    @XmlValue
    private BigDecimal value;   
    // getters, setter ...
}

It partly helped, attribute is shown correctly, but @XmlValue annotation seems to be is ignored. Value is shown in sub-element val instead of element's text.

<value cur="EUR">
    <val>1</val>
</value>

JSON examples work without any problem.

Demo project on GitHub .

Thanks for help.

Answer 1

This is an issue with the OpenAPI spec.

<value cur="EUR">1</value>

The XML structure you want to achieve is not supported by OpenAPI.

There is a GitHub issue tracking this: https://github.com/OAI/OpenAPI-Specification/issues/630