Swagger UI: explode=true ignored for object array in post request body

Question

I am trying to use Swagger to document an API POST call which has an object array parameter. But when I try to test it in Swagger UI, it seems the explode: true is ignored in encoding:filters. This is my code:

openapi: 3.0.2
info:
  description: >-
    My API
  version: 1.0.0
  title: My API
tags:
  - name: myApi
    description: my API
paths:
  /myApi/getList:
    post:
      tags:
        - myApi
      summary: gets a list
      description: gets a list
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                sourceId:
                  type: integer
                  description: the source id
               filters:
                  type: array
                  items:
                    $ref: '#/components/schemas/Filter'
            encoding:
              filters:
                contentType: application/json
                explode: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '500':
          description: error
components:
  schemas:
    Filter: 
      type: object
      properties:
        field:
          type: string
          description: the name of the field for this filter
        selection:
          type: array
          items:
            type: string
            description: the name of a selected value of the filter field
      required: [attribUniqueName, selection]

If I use as parameters e. g.

sourceId: 1

filters: [
  {
    "field": "product",
    "selection": ["Prod A", "Prod B"]
  },
  {
    "field": "country",
    "selection": ["USA", "France"]
  }
]

then Swagger UI generates a call using (if I omit the URL encoding for better readability):

sourceId=1&filters={"field":"product","selection":["Prod A","Prod B"]},{"field":"country","selection":["USA","France"]}

How can I get it to produce

sourceId=1&filters={"field":"product","selection":["Prod A","Prod B"]}&filters={"field":"country","selection":["USA","France"]}

instead?

The OpenAPI 3.0.2 documentation for "Encoding Object" states that the explode property "SHALL be ignored if the request body media type is not application/x-www-form-urlencoded." But we are using application/x-www-form-urlencoded here. Or is the documentation wrong and it should state "the content type the current object" instead of "the request body media type"? But then, I would have assumed to get a real array as the parameter value, i. e.

sourceId=1&filters=[{"field":"product","selection":["Prod A","Prod B"]},{"field":"country","selection":["USA","France"]}]

If it matters: I am using Swagger UI version 3.24.3.

Czarek Czarek · Accepted Answer · 2020-02-06T10:36:20

Your code looks good, the actual problem is that encoding is not yet supported by Swagger UI.

See here for related issue on Github. It has an example for array of strings not for array of objects like in your case but probably as long as it does not work for strings it will not work for objects either.

Swagger UI: explode=true ignored for object array in post request body

1 Answers