Geek Answers Handbook

Use object type query parameter in swagger documentation

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

When writing swagger documentation, I mostly get errors that prevent me from using schema/ types objectin a type parameter query:

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 request parameter having the value of the object will be encoded in the real request.

Despite the fact that swagger shows an error at the top of the screen, the object is rendered correctly in the swagger user interface editor, but this error spreads over the documentation.

+6
source share
3 answers

, OpenAPI 2.0. OpenAPI 3.0 , :

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

, , . , , Swagger UI OpenAPI 3.0.

+2

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

style explode , .

  • The style determines how several values ​​are separated. Possible styles depend on the location parameter - path, query, header or cookie.
  • explode (true / false) indicates whether arrays and objects should generate separate parameters for each element of the array or object properties.

For the above example, the URL would be:

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

For more information on parameter descriptions with OpenAPI v3 and parameter serialization, please refer here .

+2
source

More articles:


All Articles