Dropwizard环境下Swagger-UI无Multipart/Form-data文件上传按钮求助

问题原因 #

当前代码仅使用 @FormDataParam 标记文件参数，但未通过 Swagger 注解明确告知 OpenAPI 这是一个文件上传类型的参数，导致 Swagger-UI 无法识别并渲染上传按钮。需要补充 OpenAPI 3.x 规范的注解来描述文件参数的类型和格式。

解决方案 #

方案1：给文件参数添加 @Parameter 注解 #

直接在文件参数上补充 @Parameter 注解，明确指定参数的媒体类型和 schema 格式：

import io.swagger.core.v3.oas.annotations.Parameter;
import io.swagger.core.v3.oas.annotations.media.Content;
import io.swagger.core.v3.oas.annotations.media.Schema;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.core.MediaType;
import org.glassfish.jersey.media.multipart.FormDataContentDisposition;
import org.glassfish.jersey.media.multipart.FormDataParam;

@POST
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Operation(tags = {"bulkApi"}, summary = "Upload CSV to create employee in Bulk", description = "Upload CSV to create employee in Bulk")
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Success",
                content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
        @ApiResponse(responseCode = "401", description = "Invalid Credentials Provided",
                content = @Content(mediaType = "text/plain"))
})
public List<Employee> uploadBulk(
        @FormDataParam("file") 
        @Parameter(
            description = "CSV文件（包含员工数据）",
            required = true,
            content = @Content(
                mediaType = MediaType.APPLICATION_OCTET_STREAM,
                schema = @Schema(type = "string", format = "binary")
            )
        )
        InputStream uploadInputStream,
        
        @FormDataParam("file") 
        @Parameter(hidden = true) // 隐藏此辅助参数，避免UI重复显示
        FormDataContentDisposition fileDetails) {
    return employeeService.create(uploadInputStream);
}

方案2：使用 @RequestBody 规范定义请求体 #

更符合 OpenAPI 3.x 规范的方式是通过 @RequestBody 直接描述多部分表单请求，明确文件字段的类型：

import io.swagger.core.v3.oas.annotations.parameters.RequestBody;
import io.swagger.core.v3.oas.annotations.media.Content;
import io.swagger.core.v3.oas.annotations.media.Encoding;
import io.swagger.core.v3.oas.annotations.media.Schema;
import io.swagger.core.v3.oas.annotations.media.SchemaProperty;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.core.MediaType;
import org.glassfish.jersey.media.multipart.FormDataContentDisposition;
import org.glassfish.jersey.media.multipart.FormDataParam;

@POST
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Operation(
    tags = {"bulkApi"}, 
    summary = "Upload CSV to create employee in Bulk", 
    description = "Upload CSV to create employee in Bulk",
    requestBody = @RequestBody(
        required = true,
        content = @Content(
            mediaType = MediaType.MULTIPART_FORM_DATA,
            schema = @Schema(type = "object"),
            encoding = @Encoding(name = "file", contentType = "text/csv"), // 指定CSV格式
            schemaProperties = {
                @SchemaProperty(
                    name = "file",
                    description = "CSV文件（包含员工数据）",
                    schema = @Schema(type = "string", format = "binary")
                )
            }
        )
    )
)
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Success",
                content = @Content(mediaType = "application/json", schema = @Schema(implementation = Response.class))),
        @ApiResponse(responseCode = "401", description = "Invalid Credentials Provided",
                content = @Content(mediaType = "text/plain"))
})
public List<Employee> uploadBulk(
        @FormDataParam("file") InputStream uploadInputStream,
        @FormDataParam("file") FormDataContentDisposition fileDetails) {
    return employeeService.create(uploadInputStream);
}

额外注意事项 #

1. 注解包正确性：确保所有 Swagger 注解导入自 io.swagger.core.v3.oas.annotations 包（jakarta 版本），避免混用 javax 版本的注解。
2. Swagger 配置验证：确认 Dropwizard 中已正确配置并启用 SwaggerBundle，确保接口包能被扫描到：

   @Override
   public void initialize(Bootstrap<YourConfiguration> bootstrap) {
       bootstrap.addBundle(new SwaggerBundle<>() {
           @Override
           protected SwaggerBundleConfiguration getSwaggerBundleConfiguration(YourConfiguration configuration) {
               return configuration.getSwaggerBundleConfiguration();
           }
       });
   }
   

   配置文件中需包含：

   swagger:
     resourcePackage: com.your.api.package
     title: Employee API
     version: 1.0.0
   

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