CODEWITHSUNDEEP
openapi
AsTeR
AsTeR

Reputation: 7521

Openapi: sharing parameters and components description

I have a web service description in openapi 3.0.0 (upgrading is not an issue).

This webservice will accept several POST parameters, and it will return all of those parameters in the response. In that sense I would like to find a way of sharing the fields description.

From what I have understoop, components can be shared as schemas as response elements, parameters as well but in a different format (including fields like query), but is there away to share them both at the same place to express them as both elements from the response and from the service parameters.

A sample that I have seen is possible:


        - name: filter
          in: query
          schema:
            type: object
            allOf:
              - $ref: '#/components/schemas/SomeComponent'

Here I understand that every field in SomeComponent will be nested below filter, I would like to have them as first order parameters.

EDIT a screenshot from an open API parser that shows this nesting:

Nested OpenAPI parameters

Upvotes: 2

Views: 1741

Answers (1)

Helen
Helen

Reputation: 97677

Here I understand that every field in SomeComponent will be nested below filter, I would like to have them as first order parameters.

In OpenAPI, the serialization method for query parameters depends on the parameter's style and explode attributes. The default method is style: form + explode: true, which means the object is exploded into individual key=value pairs - just like you want. In this case, the parameter name (filter in your example) can be arbitrary as it doesn't actually appear in the request URL.

In other words, this definition

      parameters:
        - name: filter
          in: query
          schema:
            $ref: '#/components/schemas/SomeComponent'

components:
  schemas:
    SomeComponent:
      type: object
      properties:
        foo:
          type: string
        bar:
          type: string

corresponds to

...?foo=value1&bar=value2

Even though the "Parameters" section in Swagger UI displays it as a single object-type parameter, the actual HTTP request query string uses separate key=value parameters.

Upvotes: 2

Related Questions