如何在Swagger中配置同时接收JSON与文件上传的双参数？

你遇到的核心问题是OpenAPI（Swagger）规范不允许同一个POST接口同时定义body和formData类型的参数，二者互斥。你的注解配置虽然在Swagger界面显示正常，但实际后端无法正确解析两种不同的请求格式，导致JSON数据被忽略。

下面提供两种可行的解决思路：

方案一：拆分接口（最规范，推荐） #

将JSON请求和文件上传拆分为两个独立接口，各自对应匹配的请求格式，逻辑清晰且符合Swagger规范：

处理JSON请求的接口 #

// @Summary 提交模块信息（JSON格式）
// @Tags apiModules
// @Accept application/json
// @Produce json
// @Param data body apiModuleStruct true "模块信息"
// @Success 200 {object} string
// @Failure 400 {object} string
// @Router /api/upload/json [post]
// @Security ApiKeyAuth

处理文件上传的接口 #

// @Summary 上传模块文件
// @Tags apiModules
// @Accept multipart/form-data
// @Produce json
// @Param file formData file true "要上传的文件"
// @Param name formData string true "模块名称"
// @Param version formData string true "模块版本"
// @Success 200 {object} string
// @Failure 400 {object} string
// @Router /api/upload/file [post]
// @Security ApiKeyAuth

方案二：同一接口用multipart/form-data同时传输JSON和文件（需合并接口时使用） #

如果必须用同一个接口接收两种数据，统一使用multipart/form-data格式，将JSON数据作为表单的一个字符串字段传递，文件单独作为另一个表单字段：

Swagger注解配置 #

// @Summary 提交模块信息并上传文件
// @Tags apiModules
// @Accept multipart/form-data
// @Produce json
// @Param moduleInfo formData string true "模块信息（JSON格式）" example("{\"name\":\"ssm_parameter\",\"version\":\"1.0.0\"}")
// @Param file formData file true "要上传的文件"
// @Success 200 {object} string
// @Failure 400 {object} string
// @Router /api/upload [post]
// @Security ApiKeyAuth

对应的curl请求示例 #

curl -X POST 'http://127.0.0.1/api/upload' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'moduleInfo={"name":"ssm_parameter","version":"1.0.0"}' \
  -F 'file=@/path/to/your/target/file'

后端需要手动将moduleInfo字段的字符串解析为apiModuleStruct结构体（比如使用json.Unmarshal方法）。

注意：Content-Type: application/json格式无法传输文件，文件上传必须使用multipart/form-data，并通过-F参数指定表单字段，而非-d参数。

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