OpenAPI Parameters

Parameters are used to describe inputs to an operation. Parameters can be defined at the path or operation level and are merged with any duplicates at the operation level, overriding any defined at the path level.

Each parameter needs to be uniquely identified by a combination of its name and in fields in an operation.

A parameter in the list can either be a Parameter Object or a Reference to a Parameter Object defined in the Components Object under the parameters field.

Parameters can represent a number of different input types, including:

Path Parameters
Query Parameters
Headers
Cookies

Example:

paths:
  /drinks/{type}:
    parameters:
      - name: type
        in: path
        description: The type of drink to filter by.
        required: true
        schema:
          $ref: "#/components/schemas/DrinkType"
      - name: Cache-Control
        in: header
        description: The cache control header.
        required: false
        schema:
          type: string
          enum:
            - no-cache
            - no-store
            - must-revalidate
            - max-age=0
            - max-age=3600
            - max-age=86400
            - max-age=604800
            - max-age=2592000
            - max-age=31536000
    get:
      operationId: listDrinks
      summary: Get a list of drinks.
      description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      security:
        - {}
      tags:
        - drinks
      parameters:
        - name: limit
          in: query
          description: The maximum number of drinks to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: A list of drinks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"

Parameter Object

Field	Type	Required	Description
`name`	String	✅	The case sensitive name of the parameter. This *must* be unique when combined with the `in` field. If the `in` field is `path`, then this field *must* be referenced in the owning path.
`in`	String	✅	The type or location of the parameter. The available types are: `path` - A templated parameter defined within the path. `query` - A query parameter passed via the URL. `header` - A header parameter passed via HTTP headers. `cookie` - A cookie parameter passed via HTTP cookies.
`description`	String		A description of the parameter. This may contain CommonMark syntax (opens in a new tab) to provide a rich description.
`required`	Boolean		Whether the parameter is required. If the `in` field is `path`, then this field is always required and *must* be `true`. Defaults to `false`.
`deprecated`	Boolean		Whether the parameter is deprecated. Defaults to `false`.
`style`	String		Describes how the parameter value will be serialized depending on the `in` field. The available styles are `matrix`, `label`, `form`, `simple`, `spaceDelimited`, `pipeDelimited`, and `deepObject`. The default style depends on the `in` field: `path` - `simple` `query` - `form` `header` - `simple` `cookie` - `form` See the path (opens in a new tab), header (opens in a new tab), query (opens in a new tab), and cookie (opens in a new tab) parameter sections for more details.
`explode`	Boolean		Whether the parameter value will be exploded, based on the parameter type. Defaults to `true` when `style` is `form`, otherwise `false`. See the path (opens in a new tab), header (opens in a new tab), query (opens in a new tab), and cookie (opens in a new tab) parameter sections for more details.
`schema`	Schema Object		A schema or reference to a schema that defines the type of the parameter. This is *required* unless `content` is defined. Note: OpenAPI 3.0.x supports OpenAPI Reference Objects here as the value. OpenAPI 3.1.x uses the JSON Schema Referencing format.
`content`	Content		A map of Media Type Objects that defines the possible media types that can be used for the parameter. This is *required* unless `schema` is defined.
`allowEmptyValue`	Boolean		Whether the parameter value can be empty. Only used if `in` is `query`. Defaults to `false`.
`allowReserved`	Boolean		Whether the parameter value can contain reserved characters as defined by RFC 3986 (opens in a new tab). Only used if `in` is `query`. Defaults to `false`.
`example`	Any		An example of the parameter’s value. This is ignored if the `examples` field is defined.
`examples`	[Examples])examples)		A map of Example Objects and/or OpenAPI Reference Objects that define the possible examples of the parameter’s value.
`x-*`	Extensions		Any number of extension fields can be added to the parameter object that can be used by tooling and vendors.

The order of fields above is recommended for defining fields in the document.

Parameter Serialization

Depending on the parameter’s in, style, and explode fields and schema type, the parameter value will be serialized in different ways. Some combinations of schema type and parameter serialization are not valid and should be avoided.

The content field can be used instead to define complex serialization scenarios for a parameter such as serializing an object to a JSON string for including in a query parameter in the URL.