如何让Quarkus Reactive REST的FileUpload适配OpenAPI与Swagger-UI？

1. 确认依赖完整性 #

检查项目构建文件（Maven的pom.xml或Gradle的build.gradle），确保包含以下必要依赖：

• Reactive REST与Multipart支持：

  <!-- Maven 示例 -->
  <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-resteasy-reactive</artifactId>
  </dependency>
  <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-resteasy-reactive-multipart</artifactId>
  </dependency>
  

• OpenAPI/Swagger支持：

  <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-smallrye-openapi</artifactId>
  </dependency>
  

2. 给实体类添加OpenAPI注解 #

FileUpload是Quarkus内部类型，OpenAPI默认无法识别其文件上传语义，需在MultipartBody的字段上添加@Schema注解明确标记为文件类型：

import org.eclipse.microprofile.openapi.annotations.media.Schema;
import jakarta.ws.rs.core.MediaType;
import io.quarkus.resteasy.reactive.multipart.FileUpload;
import io.quarkus.resteasy.reactive.multipart.RestForm;
import io.quarkus.resteasy.reactive.multipart.PartType;

public class MultipartBody {
    @RestForm("fileUpload")
    @PartType(MediaType.APPLICATION_OCTET_STREAM)
    @Schema(type = "string", format = "binary", description = "待上传的文件")
    private FileUpload fileUpload;

    public FileUpload getFileUpload() {
        return fileUpload;
    }

    public void setFileUpload(FileUpload fileUpload) {
        this.fileUpload = fileUpload;
    }
}

3. 修正REST接口的请求类型注解 #

确保接口方法上添加@Consumes注解，指定接收multipart/form-data类型请求，让OpenAPI正确识别这是文件上传接口：

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.SecurityContext;
import jakarta.ws.rs.core.HttpHeaders;
import io.quarkus.resteasy.reactive.server.HttpServerRequest;
import jakarta.ws.rs.BeanParam;

@Path("/upload")
public class UploadResource {

    @POST
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    public Response fileUploadViaAttachment(@Context SecurityContext ctx,
                                            @Context HttpHeaders httpHeaders,
                                            @Context HttpServerRequest httpServerRequest,
                                            @BeanParam MultipartBody multipartBody) {
        // 此处编写文件上传处理逻辑
        return Response.ok().build();
    }
}

4. 验证效果 #

启动Quarkus应用后，访问默认Swagger UI路径/q/swagger-ui/，即可看到fileUpload字段渲染为标准文件上传按钮，对应的OpenAPI定义也会包含正确的文件类型描述。

若仍有问题，可在application.properties中添加以下配置确保OpenAPI扫描生效：

quarkus.smallrye-openapi.scanner.enable=true
quarkus.smallrye-openapi.path=/openapi

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