如何使用帶有 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之后添加下划線。