GraalVM原生构建下Swagger API V3文件上传显示为文本输入的修复方案

问题原因 #

GraalVM原生镜像构建时会进行静态分析优化，移除未被显式引用的类/方法。你手动通过OpenApiCustomizer构建Swagger模型（RequestBody/Schema等）的操作，依赖反射调用，但这些反射逻辑未被GraalVM检测到，导致运行时无法正确生成multipart请求体的元数据，最终Swagger UI将文件上传框识别为普通文本输入。

修复方案 #

方案1：通过注解自动生成Swagger元数据（推荐） #

移除手动构建请求体的代码，直接在Controller参数上添加Swagger注解，让springdoc自动生成正确的multipart配置，避免反射依赖问题：

@RestController
@RequestMapping("/stats")
public class StatsController {

  @PostMapping(
    consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
    produces = MediaType.APPLICATION_OCTET_STREAM_VALUE
  )
  @ResponseStatus(OK)
  public Flux<String> index(
    @RequestPart(value = "file", required = true)
    @Parameter(description = "待上传文件", content = @Content(
      mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
      schema = @Schema(type = "string", format = "binary")
    ))
    Flux<FilePart> file) {
    // 业务逻辑实现
  }
}

同时删除SwaggerConfig中的customiseOpenApi Bean，因为注解已经能自动生成正确的请求体定义。

方案2：添加GraalVM反射配置（兼容自定义场景） #

如果必须保留自定义OpenApiCustomizer的逻辑，需要将Swagger模型类添加到GraalVM反射白名单中：

1. 在项目src/main/resources/META-INF/native-image/org.springdoc/springdoc-openapi-starter-webflux-ui目录下创建reflect-config.json文件，内容如下：

[
  {
    "name": "io.swagger.v3.oas.models.media.Schema",
    "allDeclaredConstructors": true,
    "allPublicConstructors": true,
    "allDeclaredMethods": true,
    "allPublicMethods": true,
    "allDeclaredFields": true,
    "allPublicFields": true
  },
  {
    "name": "io.swagger.v3.oas.models.media.Content",
    "allDeclaredConstructors": true,
    "allPublicConstructors": true,
    "allDeclaredMethods": true,
    "allPublicMethods": true,
    "allDeclaredFields": true,
    "allPublicFields": true
  },
  {
    "name": "io.swagger.v3.oas.models.media.MediaType",
    "allDeclaredConstructors": true,
    "allPublicConstructors": true,
    "allDeclaredMethods": true,
    "allPublicMethods": true,
    "allDeclaredFields": true,
    "allPublicFields": true
  },
  {
    "name": "io.swagger.v3.oas.models.parameters.RequestBody",
    "allDeclaredConstructors": true,
    "allPublicConstructors": true,
    "allDeclaredMethods": true,
    "allPublicMethods": true,
    "allDeclaredFields": true,
    "allPublicFields": true
  }
]

方案3：升级springdoc版本 #

旧版本springdoc-openapi-starter-webflux-ui:2.6.0对GraalVM原生镜像的multipart场景支持存在兼容性问题，升级到2.7.0及以上版本可修复该问题：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.7.0</version>
</dependency>

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