Use object type query param in swagger documentation

Question

I have a GET route where I would like to encode an object parameter in the url as a query string.

When writing the swagger documentation I basically get errors that

Answer 1

This is now possible with OpenAPI 3.0.

parameters:
  - in: query
    name: values
    schema:
      type: object
      properties:
        genre_id: 
          type: integer
        author_id:
          type: integer
        title:
          type: string
      example:
       {
         "genre_id": 1,
         "author_id": 1
       }
    style: form
    explode: true

Here you can use style and explode keywords to specify how parameters should be serialised.

• style defines how multiple values are delimited. Possible styles depend on the parameter location – path, query, header or cookie.
• explode (true/false) specifies whether arrays and objects should generate separate parameters for each array item or object property.

For the above example the url will be:

https://ebookstore.build/v1/users/books/search?genre_id=1&author_id=1 

For more information on describing parameters with OpenAPI v3 and parameter serialisation, please refer here.

Answer 2

This is possible, just not with OpenAPI 2.0. OpenAPI 3.0 describes how this is possible here:

https://swagger.io/docs/specification/describing-parameters/

parameters:
- in: query
  name: filter
  # Wrap 'schema' into 'content.<media-type>'
  content:
    application/json:  # <---- media type indicates how to serialize / deserialize the parameter content
      schema:
        type: object
        properties:
          type:
            type: string
          color:
            type: string

In the meantime you could just have the query parameter as a plain old string type and then perform the serialization manually, then set the query parameter as required. This is what I'm doing until Swagger UI fully supports OpenAPI 3.0.

Answer 3

I don't think you can use "object" as query parameter in Swagger spec as query parameter only supports primitive type (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types)