Parameter

class Parameter(d: dict[str, Any] = None, name: str = None, location: ParameterLocation = None, description: str = None, required: bool = None, deprecated: bool = None, allowEmptyValue: bool = None, style: ParameterStyle = None, explode: bool = None, allowReserved: bool = None, schema: Schema = None, example: Any = None, examples: dict[str, Example] = None, content: dict[str, MediaType] = None)

Describes a single operation parameter.

A unique parameter is defined by a combination of a name and location.

Note

Due to Python having in as a reserved word, the in parameter is renamed location on this object. Internally this is still stored as in and will be serialized/deserialized as in.

property name: str

REQUIRED. The name of the parameter. Parameter names are case sensitive.

Restrictions

If location is PATH, the name field MUST correspond to a template expression occurring within the path field in the Paths Object. See Path Templating for further information.
If location is HEADER and the name field is “Accept”, “Content-Type” or “Authorization”, the parameter definition SHALL be ignored.
For all other cases, the name corresponds to the parameter name used by the in field.

property location: ParameterLocation | None

REQUIRED. The location of the parameter. Possible values are “query”, “header”, “path” or “cookie”.

— This is documented as in within the OAS specification. Because this conflicts with Python’s in keyword we use the term location, instead. This should be consistent throughout the docs.

property description: str | None: A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.

property required: bool | None: Determines whether this parameter is mandatory. If the parameter location is “path”, this field is REQUIRED and its value MUST be true. Otherwise, the field MAY be included and its default value is false.

property deprecated: bool | None: Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is false.

property allowEmptyValue: bool | None: If true, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored. Interactions between this field and the parameter’s Schema Object are implementation-defined. This field is valid only for query parameters. Use of this field is NOT RECOMMENDED, and it is likely to be removed in a later revision.

property style: ParameterStyle | None: Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of in): for “query” - “form”; for “path” - “simple”; for “header” - “simple”; for “cookie” - “form”.

property explode: bool | None: When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this field has no effect. When style is “form”, the default value is true. For all other styles, the default value is false. Note that despite false being the default for deepObject, the combination of false with deepObject is undefined.

property allowReserved: bool | None: When this is true, parameter values are serialized using reserved expansion, as defined by RFC6570, which allows RFC3986’s reserved character set, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including % outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string ([, ], #), or have a special meaning in application/x-www-form-urlencoded (-, &, +); see Appendices C and E for details. This field only applies to parameters with an in value of query. The default value is false.

property schema: Schema | None: The schema defining the type used for the parameter.

property example: Any | None: Example of the parameter’s potential value.

property examples: dict[str, Example] | None: Examples of the parameter’s potential value.

property content: dict[str, MediaType] | None: A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.