Swagger-ui: Swagger-UI can't render `content` inside a parameter

[hazardfn]

| Q | A
| ------------------------------- | -------
| Bug or feature request? | Bug
| Which Swagger/OpenAPI version? | 3.0.0
| Which Swagger-UI version? | v3.13.4
| How did you install Swagger-UI? | standalone-dist
| Which browser & version? | Firefox 61.0a1
| Which operating system? | Mac Sierra

Demonstration API definition

Try and add a query parameter referencing an object (which according to the spec is a valid thing to do)

        - name: users
          in: query
          description: List of users to query for
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserArray"

components:
  schemas:

    UserArray:
      type: array
      items:
        $ref: "#/components/schemas/User"

    User:
      required:
        - userId
        - currency
      properties:
        userId:
          type: integer
          format: int32
        currency:
          type: string

Configuration (browser query string, constructor, config.yaml)

I am using no additional config options, everything is vanilla.

Expected Behavior

The UI should offer me a nice way of typing in arrays of objects in a query param. According to the documentation this should be possible:

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

Current Behavior

Context

Just an honest labourer trying to document a horrendous API I didn't write 🤣

[hkosova]

Possible duplicate of #3558.

---

By the way, you example defines the users parameter as a _JSON string_ containing an array of objects, something like (before URL encoding):

/foo?users=[{"userId":0,"currency":"usd"},{"userId":1,"currency":"eur"}]

Is this actually the case?.. 🙀

Or are you trying to describe something like

/foo?users[0].userId=0&users[0].currency=usd&users[1].userId=1&users[1].currency=eur

?

[hazardfn]

@hkosova That is the case unfortunately, horrific I know...

Perhaps this kind of thing should never be possible then it would encourage people to write nice API's ☮️

[webron]

@hazardfn oh, trust me, we don't encourage it. the added support for it in the spec, was due to existing APIs rather than advocating it for new APIs.

[aleskovets]

@hkosova, is here a way to describe your example with openapi3? Looks like deepObject-way would not support indexes
/foo?users[0].userId=0&users[0].currency=usd&users[1].userId=1&users[1].currency=eur

[hkosova]

@aleskovets deepObject behavior is not defined for arrays, so there's currently no way describe the query string you mentioned. This limitation is discussed in the OpenAPI Specification repository:

Are indexes in the query parameter array representable?
https://github.com/OAI/OpenAPI-Specification/issues/1006#issuecomment-289196647

[ksac1]

The solution to the problem : "😱 Could not render this component, see the console." in Swagger Open API 3 can be resolved by following the link: https://swagger.io/docs/specification/describing-parameters/

[vinhlh]

@ksac1 how? when swagger-ui doesn't support ?

[ksac1]

@vinhlh : Yes, just follow the way of writing the path parameters and query parameters on the link: https://swagger.io/docs/specification/describing-parameters/

It really worked for me.

[hkosova]

@ksac1 there are two ways to define the parameter data - using schema and using content. Parameters with schema are displayed properly in Swagger UI. This issue is specifically about parameters with content.

[ksac1]

@hkosova :

[shockey]

@ksac1, @hkosova probably wrote that documentation 😉

---

To clarify for those reading along: Swagger UI is indeed missing support for content data within parameters. We're tracking this as a feature request!

[vinhlh]

@shockey do you guys have any plan to support this?
Or is there any chance that we can help/ contribute.

[jessebrennan]

Probably not the right place for this, but this issue is reference in the Swagger documentation and it seems like the documentation may no longer be accurate.

[hkosova]

@jessebrennan Thanks, the documentation has been updated to reflect that parameters with content are supported in Swagger UI 3.23.7+ and Swagger Editor 3.6.34+.

[akrz]

@hkosova This only supports simple json objects, right? Tried to use content with type array of objects but its not working.

Example case use: ?sort=[{"property":"date", "direction":"ASC"}]

Tried with:

"parameters": {
  "in": "query",
  "name": "sort",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "property": {
              "type": "string"
            },
            "direction": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

[hkosova]

@akrz if something does not work please open a new issue and fill in the details in the template.