如何使用带有 Lombok getter 的 springdoc-openapi 将 @JsonValue 用于 Swagger 枚举值

Question

给定一个 Spring 引导项目，该项目使用springdoc-openapi库公开一个OpenAPI (Swagger) 端点，该端点记录了项目的 Spring MVC controller 端点。

项目中的枚举之一在字段上使用来自@JsonValue的@JsonValue来更改枚举的 JSON 表示。 此枚举字段使用Project Lombok中的@Getter注释作为 getter 公开：

@Getter
public enum Suit {
    HEARTS("Hearts"), DIAMONDS("Diamonds"), CLUBS("Clubs"), SPADES("Spades");

    @JsonValue
    private final String name;

    Suit(String name) { this.name = name; }
}

然而，尽管 Jackson 表示基于字段，OpenAPI 端点返回的枚举表示使用enum的toString值代替：

"suit": {
  "type": "string",
  "enum": [
    "HEARTS",
    "DIAMONDS",
    "CLUBS",
    "SPADES"
  ]
}

预期的：

"suit": {
  "type": "string",
  "enum": [
    "Hearts",
    "Diamonds",
    "Clubs",
    "Spades"
  ]
}

基于springdoc-openapi#1244和swagger-core#3998 ，很明显@JsonValue注释需要应用于方法，而不是字段。 但是，上述尝试的方法和以下方法都不起作用：

@Getter @JsonValue
public enum Suit {
    HEARTS("Hearts"), DIAMONDS("Diamonds"), CLUBS("Clubs"), SPADES("Spades");

    private final String name;

    Suit(String name) { this.name = name; }
}

如何使用 Swagger 中的正确值公开此枚举，同时仍使用 Lombok 生成 getter？

Answer 1

解决方案是告诉 Lombok 在生成的 getter 方法上使用注解，在字段上使用@Getter(onMethod_ = @JsonValue) 。

public enum Suit {
    HEARTS("Hearts"), DIAMONDS("Diamonds"), CLUBS("Clubs"), SPADES("Spades");

    @Getter(onMethod_ = @JsonValue)
    private final String name;

    Suit(String name) { this.name = name; }
}

onMethod属性记录在@Getter 和 @Setter以及onX文档中：

要在生成的方法上添加注释，可以使用onMethod=@__({@AnnotationsHere}) 。 [...] 更多详情请参阅onX功能的文档。

语法有点奇怪，取决于您使用的 javac。
在 javac7 上，要使用 3 个onX特性中的任何一个，您必须将要应用于构造函数/方法/参数的注释包装在@__(@AnnotationGoesHere)中。 要应用多个注释，请使用@__({@Annotation1, @Annotation2}) 。 注释本身显然也可以具有参数。
在 javac8 及更高版本上，在onMethod 、 onParam或onConstructor之后添加下划线。