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. How

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