How to send a JSON object as part of a multipart request in Swagger Editor?

Question

I'm writing API documentation using Swagger Editor, but having a problem with a multipart POST request containing a JSON object. Here is my Swagger YAML file:

swagger: '2.0'
info:
  version: 1.0.0
  title: Documentation API
paths:
  /agent:
    post:
      consumes:
      - multipart/form-data
      produces:
      - text/html
      parameters:
      - in: query
        name: method
        description: name of method to access
        required: true
        type: string
      - in: body
        name: param
        description: parameter to send
        required: true
        schema:
            $ref: "#/definitions/Param"
      responses:
        201:
          description: item created
        400:
          description: invalid input, object invalid
        409:
          description: an existing item already exists
definitions:
  Param:           # <----------
    type: object
    required:
      - username
      - password
      - imsi
      - imei
      - deviceId
    properties:
      username:
        type: string
      password:
        type: string
      imsi:
        type: string
      imei:
        type: string
      deviceId:
        type: string  
host: 'localhost'
basePath: /v1/api
schemes:
  - https

When I execute the request, I get the curl command like this:

curl -X POST "https://localhost/v1/api/agent?method=login" -H  "accept: text/html" -H  "content-type: multipart/form-data" -F {"username":"1234567890","password":"1234567890","imsi":"310260000000000","imei":"000000000000000","deviceId":"9ca9b02b237a6dae"}

but I expect to get this:

curl -X POST "https://localhost/v1/api/agent?method=login" -H  "accept: text/html" -H  "content-type: multipart/form-data" -F 'param={"username":"1234567890","password":"1234567890","imsi":"310260000000000","imei":"000000000000000","deviceId":"9ca9b02b237a6dae"}'

That is, the body parameter should be sent with the key name param.

Solution

multipart/* requests containing JSON objects can be described using OpenAPI 3.0 but not OpenAPI/Swagger 2.0.

OpenAPI 3.0

OpenAPI 3.0 natively supports JSON objects in multipart/form-data requests:

paths:
  /agent:
    post:
      parameters:
      - in: query
        name: method
        description: name of method to access
        required: true
        schema:
          type: string

      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:

                # Here, "param" is part/parameter name in a multipart payload.
                # Parameter value is an object defined by the "Param" schema.
                # Default Content-Type for objects is application/json.
                param:
                  $ref: "#/components/schemas/Param"
      responses:
        ...

OpenAPI 2.0

In OpenAPI/Swagger 2.0, when consuming form data (application/x-www-form-urlencoded or multipart/form-data), form parameters whose value is a JSON string are described as just type: string, and you cannot define the structure of the JSON string.

paths:
  /agent:
    post:
      consumes:
      - multipart/form-data
      produces:
      - text/html
      parameters:
      - ...
      - in: formData    # <-------
        name: param
        description: parameter to send
        required: true
        type: string    # <-------

To pass in a JSON object, the operation needs to consume application/json instead:

paths:
  /agent:
    post:
      consumes:
      - application/json  # <-----
      produces:
      - text/html
      parameters:
      - ...
      - in: body
        name: param
        description: parameter to send
        required: true
        schema:
          $ref: "#/definitions/Param"

Comments

[danwild]

+1, and more examples of requestBody are around now that 3.0 is out.