Use object type query param in swagger documentati

问题:

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.

回答1:

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)

回答2:

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.

回答3:

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.