如何在Swagger中定义文件列表？自行实现后不生效该如何处理

不同版本的正确配置 #

• Swagger 2.0版本
  Swagger 2.0原生支持多文件数组定义，需指定请求类型为multipart/form-data，参数放在formData位置，配置示例如下：

paths:
  /uploadBatch:
    post:
      consumes:
        - multipart/form-data
      parameters:
        - name: fileList
          in: formData
          description: 待上传的文件列表
          required: true
          type: array
          items:
            type: file
      responses:
        200:
          description: 批量上传成功

• OpenAPI 3.0（Swagger 3.x）版本
  该版本调整了文件上传的定义方式，需放在requestBody的multipart/form-data节点下，配置示例如下：

paths:
  /uploadBatch:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fileList:
                  type: array
                  items:
                    type: string
                    format: binary
              required:
                - fileList
      responses:
        '200':
          description: 批量上传成功

常见失效排查点 #

• 检查请求媒体类型声明是否遗漏：Swagger2必须声明consumes: multipart/form-data，OpenAPI3必须在requestBody下指定multipart/form-data类型
• 检查参数位置是否正确：Swagger2的文件参数必须放在formData下，不能放在body、query等其他位置
• 若使用代码注解自动生成Swagger文档，需核对注解配置：以SpringFox为例，多文件参数需加@RequestPart注解，且在接口类或方法上添加@ApiConsumes(MediaType.MULTIPART_FORM_DATA_VALUE)注解
  

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