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

【问题标题】：How can @JsonValue be used for Swagger enum values using springdoc-openapi with a Lombok getter如何使用带有 Lombok getter 的 springdoc-openapi 将 @JsonValue 用于 Swagger 枚举值
【发布时间】：2026-02-15 08:30:02
【问题描述】：

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

项目中的一个枚举在字段上使用来自Jackson 的@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？

【问题讨论】：

标签： java jackson swagger lombok springdoc

【解决方案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 and @Setter 和 onX 文档中：

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

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

【讨论】：