SpringBoot中multipart/form-data接口如何在Swagger展示枚举可选值？

API 探路者

2026-8-13

问题解答：SpringBoot中multipart/form-data接口枚举参数在Swagger展示可选值

完全可以在Swagger中展示枚举的所有可选值，下面是具体实现方式：

1. 基础配置实现枚举自动识别

不管你使用的是springdoc-openapi（当前主流推荐）还是旧版springfox-swagger2，只要依赖配置正确，Swagger默认就能识别接口中的枚举参数。

先定义一个枚举类：

public enum FileType {
    IMAGE, DOCUMENT, VIDEO
}

然后在multipart/form-data类型的接口中直接使用该枚举作为表单参数：

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<String> uploadFile(
    @RequestPart("file") MultipartFile file,
    @RequestParam("fileType") FileType fileType
) {
    // 业务逻辑实现
    return ResponseEntity.ok("上传成功");
}

此时在Swagger页面中，fileType参数会自动展示所有枚举可选值（IMAGE、DOCUMENT、VIDEO），并且支持下拉选择。

2. 自定义枚举描述（可选）

如果需要给枚举值添加说明，让Swagger展示更清晰，可以用对应注解补充描述：

用springdoc-openapi时，使用@Schema注解：

public enum FileType {
    @Schema(description = "图片类型文件，支持JPG、PNG等格式")
    IMAGE,
    @Schema(description = "文档类型文件，支持PDF、Word等格式")
    DOCUMENT,
    @Schema(description = "视频类型文件，支持MP4、AVI等格式")
    VIDEO
}

用springfox-swagger2时，使用@ApiModelProperty注解：

public enum FileType {
    @ApiModelProperty(value = "图片类型文件，支持JPG、PNG等格式")
    IMAGE,
    @ApiModelProperty(value = "文档类型文件，支持PDF、Word等格式")
    DOCUMENT,
    @ApiModelProperty(value = "视频类型文件，支持MP4、AVI等格式")
    VIDEO
}

配置后，Swagger页面中每个枚举值会附带对应描述，方便用户理解参数含义。