Speakeasy Logo
Skip to Content
OpenAPI HubRequestsRequest Parameters in OpenAPI best practices

Parameters in OpenAPI

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:

Parameter Object

Parameter Object Fields

Field
Type
String
Required
✅
Description
The case sensitive name of the parameter. This must be unique when combined with the
field. If the
field is
, then this field must be referenced in the owning path.
Type
String
Required
✅
Description
The type or location of the parameter. The available types are:
  • - A templated parameter defined within the path.
  • - A query parameter passed via the URL.
  • - A header parameter passed via HTTP headers.
  • - A cookie parameter passed via HTTP cookies.
Type
String
Required
Description
A description of the parameter. This may contain CommonMark syntax  to provide a rich description.
Type
Boolean
Required
Description
Whether the parameter is required. If the
field is
, then this field is always required and must be
. Defaults to
.
Type
Boolean
Required
Description
Whether the parameter is deprecated. Defaults to
.
Type
String
Required
Description
Describes how the parameter value will be serialized depending on the
field. The available styles are
,
,
,
,
,
, and
. The default style depends on the
field:
  • -
  • -
  • -
  • -
See the path , header , query , and cookie  parameter sections for more details.
Type
Boolean
Required
Description
Whether the parameter value will be exploded, based on the parameter type. Defaults to
when
is
, otherwise
. See the path , header , query , and cookie  parameter sections for more details.
Required
Description
A schema or reference to a schema that defines the type of the parameter. This is required unless
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.
Required
Description
A map of Media Type Objects that defines the possible media types that can be used for the parameter. This is required unless
is defined.
Type
Boolean
Required
Description
Whether the parameter value can be empty. Only used if
is
. Defaults to
.
Type
Boolean
Required
Description
Whether the parameter value can contain reserved characters as defined by RFC 3986 . Only used if
is
. Defaults to
.
Type
Any
Required
Description
An example of the parameter's value. This is ignored if the
field is defined.
Required
Description
A map of Example Objects and/or OpenAPI Reference Objects that define the possible examples of the parameter's value.
Required
Description
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.

Last updated on