Support deep objects for query parameters with deepObject style

Content & configuration

Swagger/OpenAPI definition:

parameters:
 filterParam:
   in: query
   name: filter
   schema:
     type: object
   style: deepObject
   explode: true
   description: Options for filtering the results
   required: false

Swagger-Client usage:

SwaggerClient({
  // no special configuration is needed
})

Is your feature request related to a problem?

Many applications expect deeply nested objects in input parameters, see the discussion in swagger-ui starting from this comment: https://github.com/swagger-api/swagger-ui/issues/4064#issuecomment-357417513 In LoopBack, we are running into this problem too, see https://github.com/strongloop/loopback-next/pull/1679.

Consider the filter parameter described above (in:query style:deepObject explode:true).

Let's say the user provides the following value, for example by entering a JSON into the text area rendered by swagger-ui:

{
  "name": "ivan",
  "birth-date": {
    "gte": "1970-01-01"
  }
}

At the moment, swagger-js (and swagger-ui) silently ignores the value, produces an empty query and does not even let the user know that something went wrong.

Describe the solution you'd like

The following query string should be created by swagger-js client for the input value shown above.

filter[name]=ivan&filter[birth-date][qte]=1970-01-01

Describe alternatives you've considered

There are no alternatives as far as I can tell.

In the past, when Swagger 2.x did not support deepObject style, we were describing our filter argument as string and allowing clients to send the deep object in a JSON string. This was our custom extension that was of course not supported by swagger-js and swagger-ui, creating a suboptimal user experience.

Additional context

We are using swagger-ui-dist@3.17.0, which is the latest version published to npm. Unfortunately I am not able to tell which version of swagger-js is used by this version of swagger-ui-dist :(

The proposed serialization style is supported by https://www.npmjs.com/package/qs, which is used by http://expressjs.com as the default query parser, which means that a vast number of Node.js API servers are already expecting this serialization style.

I found the following two older comments that may be relevant:

https://github.com/swagger-api/swagger-js/pull/1140

Limitations:
deepObject does not handle nested objects. The specification and swagger.io documentation does not provide an example for serializing deep objects. Flat objects will be serialized into the deepObject style just fine.

https://github.com/swagger-api/swagger-js/pull/1140#issuecomment-333017825

As for deepObject and nested objects - that was explicitly left out of the spec, and it's ok to just Not Support It™.

@shockey @webron What's your opinion on this? If we contributed a patch to swagger-js that will serialize deeply-nested properties using the style described above, would you accept such change, despite the fact that OpenAPI specification does not explicitly describe how to serialize deeply-nested properties?

The issue does not name a file or test. Start by tracing swagger-js's query-parameter serialization entry point for OpenAPI 3 deepObject parameters, then compare its handling of nested objects with the example in the issue. Done means nested values are serialized into bracketed query keys instead of being silently ignored, with coverage for the shown filter structure.