OAS 2 此页面适用于 OpenAPI 规范版本 2（以前称为 Swagger）。要了解最新版本，请访问 OpenAPI 3 页面.

文件上传

Swagger 2.0 支持使用 Content-Type: multipart/form-data 发送的文件上传。也就是说，您的 API 服务器必须为此操作使用 multipart/form-data。

consumes:
   - multipart/form-data

操作有效负载使用 formData 参数（而不是主体参数）定义。文件参数必须具有 type: file。

paths:
   /upload:
     post:
       summary: Uploads a file.
       consumes:
         - multipart/form-data
       parameters:
         - in: formData
           name: upfile
           type: file
           description: The file to upload.

此定义对应于以下 HTTP 请求

POST /upload
Host: example.com
Content-Type: multipart/form-data; boundary=abcde12345
Content-Length: 204

--abcde12345
Content-Disposition: form-data; name="upfile"; filename="example.txt"
Content-Type: text/plain

File contents go here.
--abcde12345--

Swagger UI 使用文件输入控件显示文件参数，允许用户浏览要上传的本地文件。

上传文件 + 其他数据

文件参数可以与其他表单数据一起发送

      parameters:
        - in: formData
          name: upfile
          type: file
          required: true
          description: The file to upload.
        - in: formData
          name: note
          type: string
          required: false
          description: Description of file contents.

相应的 HTTP 请求有效负载将包含多个部分

POST /upload
Host: example.com
Content-Type: multipart/form-data; boundary=abcde12345
Content-Length: 332

--abcde12345
Content-Disposition: form-data; name="upfile"; filename="example.txt"
Content-Type: text/plain

File contents go here.
--abcde12345
Content-Disposition: form-data; name="note"

Uploading a file named "example.txt"
--abcde12345--

多个上传

您可以拥有多个命名的文件参数，每个参数单独定义

      parameters:
        - in: formData
          name: upfile1
          type: file
          required: true
        - in: formData
          name: upfile2
          type: file
          required: false
        - in: formData
          name: upfile3
          type: file
          required: false

但是，不支持上传任意数量的文件（文件数组）。有一个开放的功能请求在 https://github.com/OAI/OpenAPI-Specification/issues/254。目前，您可以使用二进制字符串数组作为上传任意数量文件的解决方法

type: array
items:
  type: string
  format: binary

请注意，这不会在 Swagger UI 中生成文件上传界面。

常见问题解答

我可以通过 PUT 上传文件吗？

Swagger 2.0 支持使用 Content-Type: multipart/form-data 的文件上传请求，但不关心 HTTP 方法。您可以使用 POST、PUT 或任何其他方法，只要操作使用 multipart/form-data 即可。有效负载仅包含原始文件内容的上传在 Swagger 2.0 中不受支持，因为它们不是 multipart/form-data。也就是说，Swagger 2.0 不支持像以下内容：

curl --upload-file archive.zip http://example.com/upload

另请注意，Swagger UI 中的文件上传仅适用于 POST 请求，因为浏览器中的 HTML 表单仅支持 GET 和 POST 方法。

我可以为上传的文件定义 Content-Type 吗？

这在 OpenAPI 3.0 中受支持，但在 OpenAPI/Swagger 2.0 中不受支持。在 2.0 中，您可以说某个操作接受文件，但您不能说此文件是特定类型或结构。

作为解决方法，可以使用 供应商扩展 来扩展此功能，例如

- in: formData
  name: zipfile
  type: file
  description: Contents of the ZIP file.
  x-mimetype: application/zip

  

没有找到您要找的内容？ 询问社区
发现错误？ 告诉我们