如何在 Spring Boot Swagger 中将描述附加到属性而不是对象

Question

对于 Spring Boot Swagger API 文档项目，我希望能够为相同类型的属性附加唯一的描述。我尝试过类似下面的代码块；

@Schema(name = "elm1", description = "elm1 description")
Element elm1;

@Schema(name = "elm2", description = "elm2 description")
Element elm2

@Schema(name = "Element", description = "Element description")
public class Element {
    Element() { }
}

这似乎创造了这样的东西；

elm1:
    $ref: '#/components/schemas/Element'
elm2:
    $ref: '#/components/schemas/Element'

这导致生成的文档仅给出一个描述，该描述对于“元素”类型的每个对象都是相同的。对于“String”或“Double”等类型，情况似乎并非如此。有没有办法为每个属性提供唯一的描述，即使它们属于同一对象类？

Answer 1

我假设您正在使用 Springdoc。如果你使用不同的东西那么 YMMV.

Swagger 模式，如您所见，只有一个对

#/components/schemas/XXX

的引用。对于值类型，它不会创建架构。

你正在做的事情是可能的，只是不通过注释。我做了一些非常相似的事情（我根据路径为相同类型给出了不同的返回示例）。

基本上，您需要创建一个

OpenApiCustomizer

并根据自己的喜好调整地图。

只是一个警告，它需要相当多的代码来浏览所有地图嵌套（并且有很多级别），但没有什么太复杂的，只是乏味。

编辑：哦，您可能需要发明自己的机制来获得您想要的正确描述，因为我认为注释在到达您的定制程序时会丢失。但它可能被埋在地图中的某个地方，但我假设它只用于生成地图，然后扔掉。

另一条评论，你可能至少要花 2-3 天才能让它发挥作用，而且大多数开发人员不会查看描述，所以......它主要适合我们强迫症患者:)。