Nested query parameters in Swagger 2.0

Question

I'm documenting a Rails app with Swagger 2.0 and using Swagger-UI as the human-readable documentation/sandbox solution.

I have a resource where clients can store arbitrary metadata to query later. According to the Rails convention, the query would be submitted like so:

/posts?metadata[thing1]=abc&metadata[thing2]=def

which Rails translates to params of:

{ "metadata" => { "thing1" => "abc", "thing2" => "def" } }

which can easily be used to generate the appropriate WHERE clause for the database.

Is there any support for something like this in Swagger? I want to ultimately have Swagger-UI give some way to modify the generated request to add on arbitrary params under the metadata namespace.

Answer 1

This doesn't appear supported yet (over 2 years after you asked the question), but there's an ongoing discussion & open ticket about adding support for this on the OpenAPI github repo. They refer to this type of nesting as deepObjects.

There's another open issue where an implementation was attempted here. Using the most recent stable swagger-ui release, however, I have observed it working as I expect:

    "parameters": [
      {
        "name": "page[number]",
        "in": "query",
        "type": "integer",
        "default": 1,
        "required": false
      },
      {
        "name": "page[size]",
        "in": "query",
        "type": "integer",
        "default": 25,
        "required": false
      }

This presents the expected dialog box & works with Try it out against a working server.

I don't believe there is a good way to specify arbitrary or a selection of values (e.g. an enum), so you may have to add parameters for every nesting option.