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でファイルアップロードインターフェイスを生成しないことに注意してください。

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は次のようなものをサポートしていません。

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

  

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