ファイルアップロード

Swagger 2.0 は、Content-Type: multipart/form-data で送信されるファイルアップロードをサポートしています。つまり、API サーバーはこの操作のために multipart/form-data を消費する必要があります。

1
consumes:
2
  - multipart/form-data

操作ペイロードは formData パラメーター (ボディパラメーターではない) を使用して定義されます。ファイルパラメーターは type: file を持つ必要があります。

1
paths:
2
  /upload:
3
    post:
4
      summary: Uploads a file.
5
      consumes:
6
        - multipart/form-data
7
      parameters:
8
        - in: formData
9
          name: upfile
10
          type: file
11
          description: The file to upload.

この定義は、次の HTTP リクエストに対応します。

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

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

10
File contents go here.
11
--abcde12345--

Swagger UI は、ファイル入力コントロールを使用してファイルパラメーターを表示し、ユーザーがアップロードするローカルファイルを参照できるようにします。

ファイルのアップロード + その他のデータ

ファイルパラメーターは、他のフォームデータと一緒に送信できます。

1
parameters:
2
  - in: formData
3
    name: upfile
4
    type: file
5
    required: true
6
    description: The file to upload.
7
  - in: formData
8
    name: note
9
    type: string
10
    required: false
11
    description: Description of file contents.

対応する HTTP リクエストペイロードには複数のパートが含まれます。

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

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

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

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

複数アップロード

いくつかの名前付きファイルパラメーターを持つことができ、それぞれ個別に定義されます。

1
parameters:
2
  - in: formData
3
    name: upfile1
4
    type: file
5
    required: true
6
  - in: formData
7
    name: upfile2
8
    type: file
9
    required: false
10
  - in: formData
11
    name: upfile3
12
    type: file
13
    required: false

ただし、任意の数のファイル (ファイルの配列) のアップロードはサポートされていません。https://github.com/OAI/OpenAPI-Specification/issues/254 で機能要求がオープンされています。今のところ、任意の数のファイルをアップロードするための回避策として、バイナリ文字列配列を使用できます。

1
type: array
2
items:
3
  type: string
4
  format: binary

ただし、これにより Swagger UI でファイルアップロードインターフェースは生成されません。

FAQ

PUT 経由でファイルをアップロードできますか？

Swagger 2.0 は Content-Type: multipart/form-data を持つファイルアップロードリクエストをサポートしていますが、HTTP メソッドは問いません。操作が multipart/form-data を消費する限り、POST、PUT、またはその他のメソッドを使用できます。ペイロードが単なる生のファイルコンテンツであるアップロードは multipart/form-data ではないため、Swagger 2.0 ではサポートされていません。つまり、Swagger 2.0 は次のようなものをサポートしません。

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

また、ブラウザの HTML フォームは GET と POST メソッドのみをサポートしているため、Swagger UI でのファイルアップロードは POST リクエストでのみ機能することにも注意してください。

アップロードされたファイルの Content-Type を定義できますか？

これは OpenAPI 3.0 でサポートされていますが、OpenAPI/Swagger 2.0 ではサポートされていません。2.0 では、操作がファイルを受け入れるとは言えますが、そのファイルが特定のタイプまたは構造であるとは言えません。

回避策として、この機能を拡張するために、例えばベンダー拡張を使用できます。

1
- in: formData
2
  name: zipfile
3
  type: file
4
  description: Contents of the ZIP file.
5
  x-mimetype: application/zip

お探しのものが見つかりませんでしたか？コミュニティに質問する
間違いを見つけましたか？お知らせください