Search code examples
swaggerswagger-uiopenapi

Array of files in Swagger

How to define a list of files in Swagger?

Here is what I did but it doesn't work.

Solution

  • OpenAPI 2.0

    In OpenAPI 2.0 (swagger: '2.0'), you have to define each file as a separate parameter. This means you can only describe requests that send a fixed/limited number of files. There is no way to define an unbound array of files.

    paths:
  /something:
    post:
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: file1
          type: file
        - in: formData
          name: file2
          type: file
        - ...

    OpenAPI 3.0

    Arrays of files are supported in OpenAPI 3.0. The request can be defined as follows:

    openapi: 3.0.0

paths:
  /something:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                # "reports" will be used as the name of each file part/field
                # in the multipart request
                reports:
                  type: array
                  items:
                    type: string
                    format: binary

    OpenAPI 3.1

    OAS 3.1 also supports file arrays, but the syntax is slightly different from 3.0. Specifically, file arrays use items: {} instead of binary string items.

    openapi: 3.1.0

paths:
  /something:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                # "reports" will be used as the name of each file part/field
                # in the multipart request
                reports:
                  type: array
                  items: {}