In Swagger, how to define an API that consumes a file along with a schema parameter?

Question

I am trying to use Swagger to define an API that accepts an actual file and a schema object that describes the contents of a file. Here is a snippet of the Swagger YAML. However it won't validate in the Swagger Editor.

/document:
  post:
    summary: Api Summary
    description: Api Description
    consumes:
      - multipart/form-data
    parameters:
      - name: documentDetails
        in: formData
        description: Document Details
        required: true
        schema:
          $ref: '#/definitions/Document'
      - name: document
        in: formData
        description: The actual document
        required: true
        type: file

The Swagger Editor throws the following validation error:

Swagger Error: Data does not match any schemas from 'oneOf'

Am I missing something? Or Is this not a supported feature of Swagger?

Answer 1

This is possible in OpenAPI 3.0, but not in OpenAPI/Swagger 2.0.

OpenAPI/Swagger 2.0 does not support objects in form data. Form parameters can be primitive values, arrays of primitives, and files, but not objects. So your example cannot be described using OpenAPI 2.0.

In OpenAPI 3.0, you can use:

paths:
  /document:
    post:
      summary: Api Summary
      description: Api Description
      requestBody:
        required: true
        content:
          multipart/form-data:

            # Form parameters from 2.0 become body schema properties in 3.0
            schema:
              type: object
              properties:

                # Schema properties correspond to individual parts
                # of the multipart request
                document:
                  # In 3.0, files are binary strings
                  type: string
                  format: binary
                  description: The actual document

                documentDetails:
                  $ref: '#/components/schemas/Document'
                  # The default Content-Type for objects is `application/json`
              required:
                - document
                - documentDetails

Relevant parts of the 3.0 Specification:
Considerations for File Uploads
Special Considerations for multipart Content

Answer 2

swagger does not support type 'object' in formData, only as body parameters.