Openapi-specification: Query parameters objects (like params[variable]=toto, ....)

[Nox-404]

Hi,
I'm gonna be a bit lazy and just post it back here, so here is a question/suggestion/request

Is there a way to describe object parameters like this :

• filter[name]=a
• filter[ip]=10.
• ...

What i got :

What i need :

The field between the brackets should be able to be a select (enum) or an input field

And when one is filled, it should add another one beneath it (and with an enum it should remove or not the selected value (configurable))

I originally posted it there

[whitlockjc]

I think this is more about tooling support. The OpenAPI specification allows you to describe parameters the way you requested already so nothing needs to change. Since you've already created an issue in swagger-ui _(https://github.com/swagger-api/swagger-ui/issues/2027)_, that's the best course of action.

Since you were already talking to @webron in the swagger-ui issue, I'll let him decide how to handle this issue.

[webron]

If I understand what @Nox-404 is asking, that's not really supported by the spec now. Query parameter _names_ are not parameterized and can't be controlled that way. You can define an enum for the values, but not for the name.

What concerns me here is the control on the type of the parameter. So if you have name it'd be a string, but if you have age it'll be an integer? Not sure how we'd represent that elegantly.

[Nox-404]

@webron yes that's what i mean, and i don't have any idea on how to describe it yet too

[webron]

Parent: #565

[whitlockjc]

I don't understand how this can't be done by OpenAPI already. Take a look at https://github.com/apigee-127/swagger-tools/issues/294 and you'll see that people are already doing this, although it's working due to the fact that the query string parsing library supports it. But in the referenced issue, you'll see how some are already doing this and it was a tooling issue to support it.

[webron]

That's a fair point. It could be a display issue only. Tools could have a way to collect filter[*] entries under one roof, though again, there's a problem with the description and the type.

It could also be a convenience issue - instead of having to repeat the same definition for each filter with a fixed name, you can have one with an enum of 'types' for the filter. Not sure this is something we need to support, but it's fair to consider.

[raymondfeng]

We have to workaround the issue today by passing stringified json to complex query parameters, for example:

filter={"where":{"name":"John"}}

[Vanuan]

@raymondfeng How do you define such format?

I tried this in the swagger editor:

      parameters:
        - name: filter
          in: query
          required: false
          schema:
            $ref: '#/definitions/Person'

But it complains that in: query isn't supported for object types:

No enum match for: query

[fehguy]

@raymondfeng @Vanuan please see here:

https://github.com/OAI/OpenAPI-Specification/pull/654

For the next spec, you will be allowed complex parameters for all locations. What's left is the serializationStrategy, which is quite different from produces and consumes. If you have thoughts on defining that, it'd be helpful.

[Vanuan]

I don't quite understand what produces and consumes are used for and how are they related to serializationStrategy.

[fehguy]

See #804

[itsjavi]

For now, until we have schemas available for all parameters in the 3.0 spec, one option is to use a string like: ?filter=with_pictures(true),ids(1,2,3),location.latitude(51.5033640) this is URL safe (excepting comma, that needs encoding) and it is shorter and simpler than using brackets for sending complex objects via query strings, where we cannot use a body (like on GET requests).

Of course the server should be able to interpret them, but for new APIs I would recommend it.

[ravanscafi]

is it possible nowadays? i'm a little bit lost