How do i enter data for nested arrays in swagger ui

Question

I'm building a web api using asp.net webapi 2 and for my documentation i've chosen to go with swagger.

The problem i'm having is that one of my api methods takes a nested array (array of strings inside another array). When testing manually in postman it works great when i type something like this:

http:/localhost:port/setup?array[0]=key1&array[0]=value1&array[1]=key2&array[1]=value2

But in swagger-ui i get one field to type in, with only one parameter per row. And that makes me unable to enter two values for each nested array.

Result should look like this (json):

[["key1","value1"],["key2","value2"]]

Which i have been able to achieve with the query parameters above. While i can only achieve the following in the swagger-ui text field:

[["key1"],["value1"],["key2"],["value2"]]

I have vacuumed the internet for 1-2 hours for an answare but can only find posts asking how to define a nested array in the yaml file. Some errands i've read on the swagger github leaves me thinking that it isn't possible at all. And while it's not a critical feature it would be really nice if all of the tests worked as they should.

So the question is, if possible, how do i type two separate strings in a nested array in swagger-ui.

I am not a pro in any of this stuff. I learned how to use json api's and swagger, all of it this week so please take that in mind while reviewing this.

Thanks in advance!

Answer 1

A nested array is simple:

type: array
items:
  type: array
  items: 
    type: string

But OpenAPI/Swagger does not have a way to serialize nested arrays in the query string like in your example.

If the array has a fixed number of items, a possible workaround is to define each nested array as a separate query parameter:

paths:
  /setup:
    get:
      parameters:
        - in: query
          name: array[0]
          required: true
          type: array
          items:
            type: string
          collectionFormat: multi   # array[0]=key1&array[0]=value1
        - in: query
          name: array[1]
          required: true
          type: array
          items:
            type: string
          collectionFormat: multi   # array[1]=key2&array[1]=value2

A better approach would be to use a POST request and pass the array in the request body:

paths:
  /setup:
    post:
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: array
            items:
              type: array
              items: 
                type: string