Swagger addCustomer接口定义疑问：为何未发送multipart请求？

首先直接给结论：你的定义不正确，要同时发送JSON数据和图片，确实需要配置成multipart/form-data类型的请求——普通的application/json请求只能传JSON，没法携带文件，这就是为什么Swagger Hub只发了JSON数据的原因。

问题出在哪？ #

如果你的addCustomer接口当前请求体配置的是application/json，那不管你怎么定义图片字段，Swagger都只会把整个请求当作JSON来发送，文件根本没法被包含进去。要同时传结构化数据和文件，必须用多部分表单（multipart）格式。

正确的Swagger配置示例 #

下面是符合需求的addCustomer接口配置模板，你可以对照修改自己的定义：

paths:
  /customers:
    post:
      summary: 添加新客户（含图片）
      operationId: addCustomer
      requestBody:
        required: true
        content:
          # 指定请求为multipart/form-data类型
          multipart/form-data:
            schema:
              type: object
              properties:
                # JSON数据部分：定义你的客户信息结构
                customerInfo:
                  description: 客户的JSON结构化数据
                  type: object
                  properties:
                    name:
                      type: string
                      example: "John Doe"
                    email:
                      type: string
                      example: "john@example.com"
                    phone:
                      type: string
                      example: "123-456-7890"
                    # 其他你需要的字段...
                # 图片文件部分：指定为二进制文件类型
                profileImage:
                  description: 客户的头像图片
                  type: string
                  format: binary
              # 必填字段，根据你的需求调整
              required:
                - customerInfo
                - profileImage
      responses:
        '201':
          description: 客户创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 123
                  message:
                    type: string
                    example: "Customer added successfully"

关键配置说明 #

• 必须将requestBody.content设置为multipart/form-data，这是多部分请求的标准类型，支持同时传输不同类型的数据
• JSON数据部分可以直接定义为object类型，Swagger会自动把它作为multipart请求里的一个表单字段
• 图片字段要设置type: string + format: binary，这样Swagger Hub的测试界面会显示文件选择框，允许你上传图片
• 记得在required数组里添加必填的字段名，确保测试时不会遗漏

后续测试注意事项 #

修改完定义后，在Swagger Hub测试时：

1. 找到addCustomer接口的测试面板
2. 在请求体区域，分别填写customerInfo的JSON内容，再通过profileImage的文件选择框上传图片
3. 发送请求，此时Swagger会生成正确的multipart请求，同时包含JSON数据和图片文件

另外也要确认你的后端服务已经做好了接收multipart/form-data请求的准备，能正确解析表单中的JSON字段和文件字段哦。

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