📒Multipart Requests

multipart request는 하나 이상의 데이터 셋을 하나의 body로 결합한다.

보통 파일 업로드에 사용하거나 single request에 여러 media type이 사용되는 경우(JSON obejct와 파일이 함께 요청으로 전송되는 경우)에 사용한다.

requestBody:
  content: 
    multipart/form-data: # Media type
      schema:            # Request payload
        type: object
        properties:      # Request parts
          id:            # Part 1 (string value)
            type: string
            format: uuid
          address:       # Part2 (object)
            type: object
            properties:
              street:
                type: string
              city:
                type: string
          profileImage:  # Part 3 (an image)
            type: string
            format: binary

requestBody/content 키워드로 시작해서 request data의 media type을 명시한다.

파일 업로드의 경우에는 보통 multipart/form-data를 사용하고, mixed-data 요청의 경우 mulpart/mixed를 사용한다.

그 아래에는 schema 키워드로 request payload에 대한 정의를 작성한다.

schema 객체의 properties로 각 part를 나눈다.

multipart request는 여러 데이터(string, object, JSON format, binary data)를 포함할 수 있고, 하나 혹은 여러 파일을 업로드할 수도 있다.

POST /upload HTTP/1.1
Content-Length: 428
Content-Type: multipart/form-data; boundary=abcde12345
--abcde12345
Content-Disposition: form-data; name="id"
Content-Type: text/plain
123e4567-e89b-12d3-a456-426655440000
--abcde12345
Content-Disposition: form-data; name="address"
Content-Type: application/json
{
  "street": "3, Garden St",
  "city": "Hillsbery, UT"
}
--abcde12345
Content-Disposition: form-data; name="profileImage "; filename="image1.png"
Content-Type: application/octet-stream
{…file content…}
--abcde12345--

✔️Specifying Content-Type

기본적으로 각 request parts의 Content-Type은 request part에 정의된 schema 프로퍼티의 type 값을 따라간다.

request part에 대해 특정 Content-Type을 설정하려면 encoding/{property-name}/contentType 필드를 사용한다.

encoding을 media type property의 자식으로 추가한다.(schema level과 맞춰서 작성한다).

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties: # Request parts
          id:
            type: string
            format: uuid
          address:
            type: object
            properties:
              street:
                type: string
              city:
                type: string
          profileImage:
            type: string
            format: base64
      encoding: # The same level as schema
        profileImage: # Property name (see above)
          contentType: image/png, image/jpeg

✔️Specifying Custom Headers

multipart 요청의 part는 Content 헤더를 제외하고 보통 header를 쓰지 않는다.

custom header를 포함해야 한다면 encoding/{property-name}/headers 필드를 사용한다.

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          profileImage:
            type: string
            format: binary
      encoding:
        profileImage: # Property name
          contentType: image/png, image/jpeg
          headers: # Custom headers
            X-Custom-Header:
              description: This is a custom header
              schema:
                type: string

POST /upload HTTP/1.1
Content-Length: 428
Content-Type: multipart/form-data; boundary=abcde12345
--abcde12345
Content-Disposition: form-data; name="id"
Content-Type: text/plain
123e4567-e89b-12d3-a456-426655440000
--abcde12345
Content-Disposition: form-data; name="profileImage"; filename="image1.png"
Content-Type: image/png
X-Custom-Header: x-header
{…file content…}
--abcde12345--