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 disallow me to use schema/object types in a query type parameter:

paths:
  /mypath/:
    get:
      parameters
        - in: path
          name: someParam
          description: some param that works
          required: true
          type: string
          format: timeuuid #good param, works well
        - $ref: "#/parameters/mySortingParam" #this yields an error

parameters:
  mySortingParam
    name: paging
    in: query
    description: Holds various paging attributes
    required: false
    schema:
      type: object
      properties:
        pageSize:
          type: number
        cursor:
          type: object
          properties:
            after:
              type: string
              format: string

The request query param having an object value would be encoded in an actual request.

Even though swagger shows an error at the top of the screen the object is rendered correctly in the swagger UI editor, however with that error floating on top of the documentation.

score 15 · Accepted Answer · answered Jul 04 '16 at 16:13

15

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)

answered Jul 04 '16 at 16:13

William Cheng

10,137
5
54
79

1

Rather disappointed at this as the documentation on swagger.io implies otherwise: https://swagger.io/docs/specification/describing-parameters/. See the section under schema vs content. While the link above describes turning an object into a content type such as JSON, it stops short of giving an example that directly relates to the OP's query. – Daniel Maclean Aug 28 '17 at 14:23
3

@DanielMaclean: The link you posted is about OpenAPI 3.0, whereas the answer is about OpenAPI/Swagger 2.0 (3.0 did not exist in 2016). The 2.0 version of that link is https://swagger.io/docs/specification/2-0/describing-parameters/ – Helen Jan 23 '18 at 09:43

score 15 · Answer 2 · edited Oct 29 '18 at 19:13

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.

score 2 · Answer 3 · edited Oct 29 '18 at 19:16

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.

edited Oct 29 '18 at 19:16

Helen

87,344
17
243
314

answered Aug 28 '17 at 14:49

Daniel Maclean

779
10
21

Just a heads up - this example is for a _JSON string_ in the query string, i.e. (before URL encoding) `GET /something?filter={"type":"foo","color":"red"}`. Whereas the OP probably wants to serialize the object into individual key/value parameters in the query string, i.e. `GET /something?type=foo&color=red`. The latter is explained in [Chaythanya nair's answer](https://stackoverflow.com/a/51277233/113116). – Helen Oct 29 '18 at 19:21

Use object type query param in swagger documentation

3 Answers3

Linked

Related