如何为Swagger-UI文档中的每个枚举值添加描述？

嘿，要给Swagger-UI里的枚举值加上描述其实不难，主要看你用的是Springfox（老版Swagger）还是现在更流行的SpringDoc（OpenAPI 3.x），我给你分两种情况一步步说：

你需要在枚举的每个实例上添加@ApiModelProperty注解来指定描述，同时可以配合@JsonValue让Swagger展示枚举的code值而不是枚举名称（可选）。修改后的枚举类代码如下：

@ApiModel(description = "运营商选择替代信息枚举")
public enum EnumCarrierSelectionSubstitutionInformation {
    @ApiModelProperty(value = "描述1：比如代表优先选择默认运营商")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_1(1),
    
    @ApiModelProperty(value = "描述2：代表允许替代为同类型运营商")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_2(2),
    
    @ApiModelProperty(value = "描述3：代表禁止任何运营商替代")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_3(3),
    
    @ApiModelProperty(value = "描述4：代表仅允许替代为指定运营商列表")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_4(4),
    
    @ApiModelProperty(value = "描述5：代表根据网络状况自动选择替代")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_5(5),
    
    @ApiModelProperty(value = "描述6：代表用户手动指定替代运营商")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_6(6);

    private final int code;

    EnumCarrierSelectionSubstitutionInformation(int code) {
        this.code = code;
    }

    // 可选：让Swagger展示code值而非枚举名称
    @JsonValue
    public int getCode() {
        return code;
    }
}

另外，如果你的Springfox版本需要额外配置枚举支持，可以在Swagger配置类里添加相关设置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.project.package"))
                .paths(PathSelectors.any())
                .build()
                // 可选：将枚举类型替换为code类型展示
                .directModelSubstitute(EnumCarrierSelectionSubstitutionInformation.class, Integer.class)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("你的API文档")
                .version("1.0")
                .build();
    }
}

现在SpringDoc是官方推荐的Swagger替代方案，用法更简洁，只需要在枚举实例上添加@Schema注解即可：

@Schema(description = "运营商选择替代信息枚举")
public enum EnumCarrierSelectionSubstitutionInformation {
    @Schema(description = "描述1：优先选择默认运营商")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_1(1),
    
    @Schema(description = "描述2：允许替代为同类型运营商")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_2(2),
    
    @Schema(description = "描述3：禁止任何运营商替代")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_3(3),
    
    @Schema(description = "描述4：仅允许替代为指定运营商列表")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_4(4),
    
    @Schema(description = "描述5：根据网络状况自动选择替代")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_5(5),
    
    @Schema(description = "描述6：用户手动指定替代运营商")
    CARRIER_SELECTION_SUBSTITUTION_INFORMATION_6(6);

    private final int code;

    EnumCarrierSelectionSubstitutionInformation(int code) {
        this.code = code;
    }

    // 可选：让Swagger展示code值而非枚举名称
    @JsonValue
    public int getCode() {
        return code;
    }
}

SpringDoc默认会自动识别这些注解，启动项目后访问/swagger-ui.html就能看到每个枚举值的描述了。如果需要调整枚举的展示细节，可以在application.properties里添加配置：

# 展开枚举的详细信息
springdoc.swagger-ui.default-model-expand-depth=2
# 显示枚举的名称和值
springdoc.swagger-ui.display-enum-values=true

• 确保项目已经引入了对应的依赖：Springfox需要springfox-swagger2和springfox-swagger-ui；SpringDoc需要springdoc-openapi-starter-webmvc-ui
• 如果枚举是作为请求参数或响应字段使用的，要确保对应的DTO或接口参数上也正确使用了@ApiModelProperty（Springfox）或@Schema（SpringDoc）注解关联这个枚举
• Spring Boot 2.6+版本建议使用Springfox 3.0.0+或者直接用SpringDoc，避免版本兼容问题

内容的提问来源于stack exchange，提问作者Pascal