Swagger/openapi 将 @Schema(description) 添加到每个枚举值

Question

我正在使用 Swagger/OpenApi V3 注释创建应用程序的 API 描述，从以下依赖项导入：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.0</version>
</dependency>

我想为每个枚举值添加描述：

public enum Gender {

    @Schema(description = "NotSpecified")
    NOT_SPECIFIED,

    @Schema(description = "Male")
    MALE,

    @Schema(description = "Female")
    FEMALE;
}

但是 springdoc 不会生成 enum 的描述。

Gender:
  type: string
  example: MALE
  enum:
  - NOT_SPECIFIED
  - MALE
  - FEMALE

有没有办法为每个枚举值添加描述？

Answer 1

我相信你只能在枚举的描述中描述枚举值（https://swagger.io/docs/specification/data-models/enums/）。所以你可以这样做：

@Schema(enumAsRef = true, description = "gender: \n" +
        "* `NOT_SPECIFIED` - NotSpecified\n" +
        "* `MALE` - Male\n" +
        "* `FEMALE` - Female\n" +
        "")
enum Gender {
    NOT_SPECIFIED,
    MALE,
    FEMALE
}

生成的招摇看起来相当不错。