springdoc-openapi、swagger UI 中的 XML 示例

Question

我正在努力在springdoc-openapi库中生成正确的 XML 示例。

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 ...
}

使用 header 调用的端点Accept: application/xml返回预期结果：

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

但是，springdoc 中似乎忽略了 Jackson 注释。 swagger-ui 中显示的示例显示：

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

我还尝试添加 JAXB 注释。

@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 ...
}

它在一定程度上有所帮助，属性显示正确，但@XmlValue注释似乎被忽略了。 值显示在子元素val中，而不是元素的文本中。

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

JSON 示例可以正常工作。

GitHub 上的演示项目。

感谢帮助。

Answer 1

这是 OpenAPI 规范的一个问题。

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

OpenAPI不支持你想要实现的XML结构。

有一个跟踪此问题的 GitHub 问题： https://github.com/OAI/OpenAPI-Specification/issues/630