How to format a JSON array in the request body of a multipart/form-data request with OpenAPI 3?

Question

I'm trying to write the OpenAPI 3 specs for an existing endpoint. The endpoint uses Content-Type of multipart/form-data and one of the parameters accepts a JSON array string. The following curl shows an example of this endpoint working correctly:

curl -X 'POST' \
  'https://testing.org/test/' \
  -H 'accept: */*' \
  -H 'Content-Type: multipart/form-data' \
  -F 'simple=abc' \
  -F 'complex=[{"key": "string", "size": 0}"]'

My OpenAPI 3 specs currently look like the following:

openapi: 3.0.3
info:
  title: Simple
  description: Testing
  version: '1.0'
servers:
  - url: 'https://testing.org'
paths:
  /test/:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                simple: 
                  type: string
                complex:
                  type: array
                  items:
                      type: object
                      properties:
                        key: 
                          type: string
                        size: 
                          type: integer
            encoding:
              complex:
                contentType: application/json
      responses:
        '200':
          description: OK

However, using the "test it out" functionality in swagger editor results in a request that looks like this:

curl -X 'POST' \
  'https://testing.org/test/' \
  -H 'accept: */*' \
  -H 'Content-Type: multipart/form-data' \
  -F 'simple=abc' \
  -F 'complex=["{\n  \"key\": \"string\",\n  \"size\": 0\n}"]'

with the complex parameter not formatted correctly. If I removed the encoding portion of the specs, this is what the request looks like:

curl -X 'POST' \
  'https://testing.org/test/' \
  -H 'accept: */*' \
  -H 'Content-Type: multipart/form-data' \
  -F 'simple=abc' \
  -F 'complex={
  "key": "string",
  "size": 0
}'

which is a JSON object but not a JSON array.

Any advice on how to format the OpenAPI 3 specs so that complex form parameter is formatted as a simple JSON array [{"key": "string", "size": 0}"]? Thank you!

Answer 1

Your API definition is correct. It should even work without encoding because the Content-Type for objects and arrays of objects is application/json by default.

The problem is that Swagger UI and Swagger Editor do not properly support JSON in multipart bodies yet. Here are the related issues you can track:

• Encoding attribute is not respected on the request
• Generated CURL seems wrong for mime/multipart uploads that have JSON parts - missing 'type=' option, wrong quotes
• multipart/form-data should support custom content-type selection