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

【问题标题】：Swagger/openapi add @Schema(description) to each enum valueSwagger/openapi 将 @Schema(description) 添加到每个枚举值
【发布时间】：2021-09-15 23:32:06
【问题描述】：

我正在使用从以下依赖项导入的 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 不会为枚举生成描述。

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

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

【问题讨论】：

标签： java swagger openapi springdoc

【解决方案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
}

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

【讨论】：