Describing a json parameter in Swagger

Question

Issue

According to this and this Swagger supports complex parameters, but when I try to describe a json parameter Swagger Editor shows the following issue:

Could not render ParameterRow, see the console.

Expected behavior

Json object as a parameter.

YAML

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Trackmeeasy API
paths:
  /getLabelUrl.action:
    post:
      parameters:
        - in: query
          name: filter
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  color:
                    type: string
      responses:
        '200':
          description: OK

To reproduce...

1. Copy yaml
2. Go to http://editor.swagger.io
3. Paste yaml
4. See error

Screenshot

Answer 1

OpenAPI 3.0 parameters with content are supported in Swagger UI 3.23.8+ and Swagger Editor 3.6.34+.

If you use an earlier version of UI or Editor, you can use this workaround to get "try it out" support - i.e. define the parameter as just type: string and add an example of the JSON data. You lose the ability to describe the JSON schema for the query string, but "try it out" will work.

      parameters:
        - in: query
          name: filter
          schema:
            type: string                           # <-------
          example: '{"type":"foo","color":"bar"}'  # <-------

Note: If you are designing a new API rather than describing an existing API, you should post complex data, such as JSON objects, in the request body instead:

openapi: 3.0.0
...
paths:
  /getLabelUrl.action:
    post:
      requestBody:    # <-----
        content:
          application/json:
            schema:
              type: object
              ...

Or if using a query parameter is more appropriate, consider "flattening" the object into key=value pairs, e.g.:

POST /getLabelUrl.action?type=foo&color=bar

This serialization strategy is defined using style: form and explode: true. See here for more example of query parameter serialization.

openapi: 3.0.0
...
paths:
  /getLabelUrl.action:
    post:
      parameters:
        - in: query
          name: filter
          schema:
            type: object
            properties:
              type:
                type: string
              color:
                type: string

          # style=form + explode=true is the default serialization strategy
          # so you can omit this
          style: form
          explode: true