OpenApi Multipart请求含JSON与文件上传：Swagger UI无选项求更佳方案

你的问题核心是Swagger UI无法识别Multipart请求中的文件上传部分，因为原代码的OpenAPI注解配置没有正确定义multipart请求的各个部件结构。以下是修正后的代码和关键说明：

修正后的代码 #

@PostMapping(path = "", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@Operation(summary = "XX", 
           requestBody = @RequestBody(description = "Das zu erstellende Ticket", 
               content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE, 
                   schema = @Schema(type = "object", 
                       properties = {
                           @Schema(name = "ticket", type = "object", implementation = TicketDTO.class, mediaType = MediaType.APPLICATION_JSON_VALUE),
                           @Schema(name = "files", type = "array", items = @Schema(type = "string", format = "binary"), mediaType = MediaType.MULTIPART_FORM_DATA_VALUE)
                       }))))
TicketDTO createTicket(@RequestPart(name = "ticket", required = true) TicketDTO ticket,
                       @RequestPart(name = "files", required = false) MultipartFile[] files)
        throws MessagingException;

关键修正点 #

• 明确Multipart请求结构：在@Operation的requestBody中，直接指定content为multipart/form-data，并通过schema的properties分别定义两个请求部件：
  • ticket：指定媒体类型为application/json，关联TicketDTO作为数据结构
  • files：指定类型为数组，子项格式为binary（这是Swagger识别文件上传的关键标记）
• 简化参数注解：移除@RequestPart上多余的@Parameter注解，避免与requestBody中的元数据冲突，同时确保@RequestPart的name与schema中定义的部件名称完全一致
• 对齐媒体类型：确保文件部件的媒体类型与请求的consumes属性匹配，让Swagger UI正确渲染文件上传控件

额外检查项 #

• 确认项目依赖的SpringDoc/Swagger版本为最新稳定版，旧版本对Multipart请求的注解支持存在缺陷
• 确保TicketDTO中的字段都添加了@Schema注解，方便Swagger UI展示完整的JSON结构

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