文件上传

在OpenAPI 3.0中，您可以描述随请求内容直接上传的文件以及通过multipart请求上传的文件。使用requestBody关键词来描述包含文件的请求体。在content下，指定请求媒体类型（例如image/png或application/octet-stream）。文件使用type: string模式，格式为format: binary或format: base64，具体取决于文件内容的编码方式。例如

1
requestBody:
2
  content:
3
    image/png:
4
      schema:
5
        type: string
6
        format: binary

此定义对应如下所示的HTTP请求

1
POST /upload
2
Host: example.com
3
Content-Length: 808
4
Content-Type: image/png
5

6
[file content goes there]

通过Multipart请求上传

要描述随其他数据一起发送的文件，请使用multipart媒体类型。例如

1
requestBody:
2
  content:
3
    multipart/form-data:
4
      schema:
5
        type: object
6
        properties:
7
          orderId:
8
            type: integer
9
          userId:
10
            type: integer
11
          fileName:
12
            type: string
13
            format: binary

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

1
POST /upload
2
Host: example.com
3
Content-Length: 2740
4
Content-Type: multipart/form-data; boundary=abcde12345
5

6
--abcde12345
7
Content-Disposition: form-data; name="orderId"
8

9
1195
10
--abcde12345
11
Content-Disposition: form-data; name="userId"
12

13
545
14
--abcde12345
15
Content-Disposition: form-data; name="fileName"; filename="attachment.txt"
16
Content-Type: text/plain
17

18
[file content goes there]
19
--abcde12345--

多文件上传

使用multipart媒体类型来定义上传任意数量的文件（文件数组）

1
requestBody:
2
  content:
3
    multipart/form-data:
4
      schema:
5
        type: object
6
        properties:
7
          filename:
8
            type: array
9
            items:
10
              type: string
11
              format: binary

相应的HTTP请求将如下所示

1
POST /upload
2
Host: example.com
3
Content-Length: 2740
4
Content-Type: multipart/form-data; boundary=abcde12345
5

6
--abcde12345
7
Content-Disposition: form-data; name="fileName"; filename="file1.txt"
8
Content-Type: text/plain
9

10
[file content goes there]
11
--abcde12345
12
Content-Disposition: form-data; name="fileName"; filename="file2.png"
13
Content-Type: image/png
14

15
[file content goes there]
16
--abcde12345
17
Content-Disposition: form-data; name="fileName"; filename="file3.jpg"
18
Content-Type: image/jpeg
19

20
[file content goes there]
21
--abcde12345--

参考

有关OpenAPI中文件上传的更多信息，请参阅OpenAPI 3.0规范的以下部分

文件上传的注意事项

multipart内容的特殊注意事项

没有找到您需要的信息？咨询社区
发现错误？告诉我们