java 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
}

而由此产生的昂首阔步看起来相当不错