profile
viewpoint

Ask questionsSupport deep objects for query parameters with deepObject style

Background

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 a filter parameter defined as follows:

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

Let's say the user wants to provide 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, the OpenAPI Specification v3 does not describe how to encode such value in a query string. As a result, OpenAPI clients like swagger-ui don't know how to handle this input - see the discussion in https://github.com/swagger-api/swagger-js/issues/1385 for an example.

Proposal

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

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 am not sure if there is any existing formal specification of this format, I am happy to look into that once my proposal gets considered as acceptable in principle.

Additional information

Existing issues that are touching a similar topic:

  • style: form + object looses the parameter name? #1006
  • Are indexes in the query parameter array representable? #1501

Two older comments from swagger-js 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™.

OAI/OpenAPI-Specification

Answer questions everlast240

Hey guys, I've been trying different things for some time now, but can't get the standard JSONAPI sparse fieldsets params to work with swagger-ui... JSONAPI specifies a way to fetch only required attributes of the included resources. E.g.:

fields[resource1]=attrib1,attrib2,attrib3&fields[resource2]=attrib1
// example:
fields[person]=first_name,last_name,age&fields[address]=city,full_address,latitude,longitude

This all works for my endpoints, but no matter how I format the payload I enter in SwaggerUI and/or setup the swagger JSON, I can't get it to work... For example, using the endpoint(s) works like that:

curl -X GET "http://localhost:5000/person/39?include=address,address.country&fields[person]=first_name,last_name,age&fields[address]=city,full_address,latitude,longitude"

Tried different swagger JSON setups (e.g.with deepObject etc), and payloads in the swagger-ui text field (e.g.: {person: "first_name,last_name,age", address: "city,full_address,latitude,longitude"}), but no success for now... Part of the complication is that the object / hash keys (model / resource name) are dynamic: they depend on the included resources (in the compound document) and I can't statically describe the schema definition.

Any ideas? Help is appreciated! PS: Using Grape (https://github.com/ruby-grape/grape/) and the Netfix fast_jsonapi (https://github.com/Netflix/fast_jsonapi).

useful!
source:https://uonfu.com/
Github User Rank List