如何在OpenAPI 3.0与Swagger UI中配置multipart/form-data文件上传？

开发者阿泽

2026-7-3

OpenAPI 3.0 二进制文件上传（multipart/form-data）配置修复

错误原因及修复方案

路径格式错误：所有接口路径必须以/开头，比如正确写法为/v1/especialidades，不能省略开头的斜杠。
移除过时字段：OpenAPI 3.0已废弃consumes和produces字段，请求的媒体类型需在requestBody.content中指定。
修复YAML缩进：YAML对缩进层级敏感，确保每个映射条目缩进一致（建议用2或4个空格），避免缩进错误。
文件参数配置错误：OpenAPI 3.0中文件上传不能通过parameters定义——in字段仅支持path/query/header/cookie，不支持formData（这是2.x版本的用法）。需将文件及其他表单字段统一放在requestBody的multipart/form-data内容块中。

正确配置示例

openapi: 3.0.3
info:
  title: 示例文件上传API
  version: 1.0.0
paths:
  /v1/especialidades:
    post:
      summary: 上传二进制文件
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                # 可选：其他表单字段
                descricao:
                  type: string
                  description: 文件描述信息
                # 二进制文件字段
                arquivo:
                  type: string
                  format: binary
                  description: 需要上传的二进制文件
      responses:
        '200':
          description: 文件上传成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: 上传后返回的文件ID