SpringDoc OpenAPI 处理多文件与JSON混合请求的415错误解析

问题背景

在使用SpringDoc OpenAPI构建RESTful API文档时，开发者可能会遇到一个常见场景：需要处理同时包含文件上传和JSON数据的复杂请求。这类接口在Spring Boot应用中通常用于接收多部分表单数据，但在实际使用Swagger UI测试时却可能遭遇415(Unsupported Media Type)错误。

问题现象

在Spring Boot 3.3.1与springdoc-openapi-starter-webmvc-ui 2.6.0环境下，当控制器方法设计为同时接收多个文件和JSON负载时，通过Swagger UI发送的请求会被服务器拒绝。具体表现为：

1. 前端收到415状态码响应
2. 后端日志显示错误："Content-Type 'application/octet-stream' is not supported"
3. 预期行为是应该正常接收请求并返回200状态码

技术分析

这个问题的根源在于Spring MVC对多部分请求的处理机制与Swagger UI生成的请求格式之间存在不匹配。当接口设计为接收混合类型参数时：

1. 控制器方法通常使用@RequestPart注解标注各个部分
2. 文件部分期望以multipart/form-data格式传输
3. JSON部分需要明确指定内容类型

问题发生时，Swagger UI生成的请求可能没有正确设置各个部分的内容类型，特别是对于非文件部分。Spring MVC的严格内容类型检查机制会因此拒绝请求。

解决方案

解决这个问题的关键在于确保API文档正确描述多部分请求的格式，并指导Swagger UI生成符合要求的请求。以下是几种可行的解决方案：

1. 显式指定内容类型：在@RequestPart注解中明确指定JSON部分的内容类型为application/json

2. 调整Swagger配置：通过自定义OpenAPI配置确保多部分请求的文档正确生成

3. 使用DTO对象：将JSON参数封装到DTO对象中，简化接口设计

最佳实践

对于需要处理复杂多部分请求的Spring Boot应用，建议采用以下实践：

1. 为每个非文件部分明确指定媒体类型
2. 在Swagger UI测试前，检查生成的请求格式是否符合预期
3. 考虑使用Postman等工具进行辅助测试
4. 保持Spring Boot和SpringDoc OpenAPI版本的兼容性

总结

处理多文件与JSON混合请求时的415错误是Spring Web应用开发中的常见挑战。通过理解Spring MVC的内容协商机制和Swagger UI的请求生成逻辑，开发者可以有效地解决这类问题。关键在于确保API文档准确描述请求格式，并验证生成的请求符合服务器期望。