Request content type: requestBody.content.\
Response content type: responses.\.content.\
Describing Request Body,
Describing Responses,
Media Types
.content.` | Describing Responses,
Media Types
|
| `Authorization` | `securitySchemes`, `security` | [Authentication](/docs/open-api-guide/authentication.md) |
### Cookie Parameters
Operations can also pass parameters in the `Cookie` header, as `Cookie: name=value`. Multiple cookie parameters are sent in the same header, separated by a semicolon and space.
{% code lineNumbers="true" %}
```yaml
GET /api/users
Host: example.com
Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCUOJ
```
{% endcode %}
Use `in: cookie` to define cookie parameters:
{% code lineNumbers="true" %}
```yaml
parameters:
- in: cookie
name: debug
schema:
type: integer
enum: [0, 1]
default: 0
- in: cookie
name: csrftoken
schema:
type: string
```
{% endcode %}
Cookie parameters can be primitive values, arrays and objects. Arrays and objects are serialized using the `form` style. For more information, see [Parameter Serialization](/docs/open-api-guide/parameter-serialization.md).
**Note:** To define cookie authentication, use [API keys](/docs/open-api-guide/authentication/api-keys.md) instead.
### Required and Optional Parameters
By default, OpenAPI treats all request parameters as optional. You can add `required: true` to mark a parameter as required. Note that path parameters must have `required: true`, because they are always required.
{% code lineNumbers="true" %}
```yaml
parameters:
- in: path
name: userId
schema:
type: integer
required: true # <----------
description: Numeric ID of the user to get.
```
{% endcode %}
### schema vs content
To describe the parameter contents, you can use either the `schema` or `content` keyword. They are mutually exclusive and used in different scenarios. In most cases, you would use **`schema`**. It lets you describe primitive values, as well as simple arrays and objects serialized into a string. The serialization method for array and object parameters is defined by the `style` and `explode` keywords used in that parameter.
{% code lineNumbers="true" %}
```yaml
parameters:
- in: query
name: color
schema:
type: array
items:
type: string
# Serialize as color=blue,black,brown (default)
style: form
explode: false
```
{% endcode %}
**`content`** is used in complex serialization scenarios that are not covered by `style` and `explode`. For example, if you need to send a JSON string in the query string like so:
{% code lineNumbers="true" %}
```yaml
filter={"type":"t-shirt","color":"blue"}
```
{% endcode %}
In this case, you need to wrap the parameter `schema` into `content/` as shown below. The `schema` defines the parameter data structure, and the media type (in this example – `application/json`) serves as a reference to an external specification that describes the serialization format.
{% code lineNumbers="true" %}
```yaml
parameters:
- in: query
name: filter
# Wrap 'schema' into 'content.'
content:
application/json: # <---- media type indicates how to serialize / deserialize the parameter content
schema:
type: object
properties:
type:
type: string
color:
type: string
```
{% endcode %}
**Note for Swagger UI and Swagger Editor users:** Parameters with `content` are supported in Swagger UI 3.23.7+ and Swagger Editor 3.6.34+.
### Default Parameter Values
Use the `default` keyword in the parameter schema to specify the default value for an optional parameter. The default value is the one that the server uses if the client does not supply the parameter value in the request. The value type must be the same as the parameter’s data type. A typical example is paging parameters such as `offset` and `limit`:
{% code lineNumbers="true" %}
```yaml
GET /users
GET /users?offset=30&limit=10
```
{% endcode %}
Assuming `offset` defaults to 0 and `limit` defaults to 20 and ranges from 0 to 100, you would define these parameters as:
{% code lineNumbers="true" %}
```yaml
parameters:
- in: query
name: offset
schema:
type: integer
minimum: 0
default: 0
required: false
description: The number of items to skip before starting to collect the result set.
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
default: 20
required: false
description: The number of items to return.
```
{% endcode %}
### **Common Mistakes**
There are two common mistakes when using the `default` keyword:
* Using `default` with `required` parameters or properties, for example, with path parameters. This does not make sense – if a value is required, the client must always send it, and the default value is never used.
* Using `default` to specify a sample value. This is not intended use of `default` and can lead to unexpected behavior in some Swagger tools. Use the `example` or `examples` keyword for this purpose instead. See [Adding Examples](/docs/open-api-guide/adding-examples.md).
### Enum Parameters
You can restrict a parameter to a fixed set of values by adding the `enum` to the parameter’s `schema`. The enum values must be of the same type as the parameter data type.
{% code lineNumbers="true" %}
```yaml
parameters:
- in: query
name: status
schema:
type: string
enum:
- available
- pending
- sold
```
{% endcode %}
More info: [Defining an Enum](/docs/open-api-guide/data-models-schemas/enums.md).
### Constant Parameters
You can define a constant parameter as a required parameter with only one possible value:
{% code lineNumbers="true" %}
```yaml
parameters:
- in: query
name: rel_date
required: true
schema:
type: string
enum:
- now
```
{% endcode %}
The `enum` property specifies possible values. In this example, only one value can be used, and this will be the only value available in the Swagger UI for the user to choose from.
**Note:** A constant parameter is not the same as the [default parameter value](#default). A constant parameter is always sent by the client, whereas the default value is something that the server uses if the parameter is not sent by the client.
### Empty-Valued and Nullable Parameters
Query string parameters may only have a name and no value, like so:
{% code lineNumbers="true" %}
```yaml
GET /foo?metadata
```
{% endcode %}
Use `allowEmptyValue` to describe such parameters:
{% code lineNumbers="true" %}
```yaml
parameters:
- in: query
name: metadata
schema:
type: boolean
allowEmptyValue: true # <-----
```
{% endcode %}
OpenAPI 3.0 also supports `nullable` in schemas, allowing operation parameters to have the `null` value. For example, the following schema corresponds to `int?` in C# and `java.lang.Integer` in Java:
{% code lineNumbers="true" %}
```yaml
schema:
type: integer
format: int32
nullable: true
```
{% endcode %}
**Note:** `nullable` is not the same as an optional parameter or an empty-valued parameter. `nullable` means the parameter value can be `null`. Specific implementations may choose to map an absent or empty-valued parameter to `null`, but strictly speaking these are not the same thing.
### Parameter Examples
You can specify an `example` or multiple `examples` for a parameter. The example value should match the parameter schema. Single example:
{% code lineNumbers="true" %}
```yaml
parameters:
- in: query
name: limit
schema:
type: integer
minimum: 1
example: 20
```
{% endcode %}
Multiple named examples:
{% code lineNumbers="true" %}
```yaml
parameters:
- in: query
name: ids
description: One or more IDs
required: true
schema:
type: array
items:
type: integer
style: form
explode: false
examples:
oneId:
summary: Example of a single ID
value: [5] # ?ids=5
multipleIds:
summary: Example of multiple IDs
value: [1, 5, 7] # ?ids=1,5,7
```
{% endcode %}
For details, see [Adding Examples](/docs/open-api-guide/adding-examples.md).
### Deprecated Parameters
Use `deprecated: true` to mark a parameter as deprecated.
{% code lineNumbers="true" %}
```yaml
- in: query
name: format
required: true
schema:
type: string
enum: [json, xml, yaml]
deprecated: true
description: Deprecated, use the appropriate `Accept` header instead.
```
{% endcode %}
### Common Parameters
**Common Parameters for All Methods of a Path**
Parameters shared by all operations of a path can be defined on the path level instead of the operation level. Path-level parameters are inherited by all operations of that path. A typical use case are the GET/PUT/PATCH/DELETE operations that manipulate a resource accessed via a path parameter
{% code lineNumbers="true" %}
```yaml
paths:
/user/{id}:
parameters:
- in: path
name: id
schema:
type: integer
required: true
description: The user ID
get:
summary: Gets a user by ID
...
patch:
summary: Updates an existing user with the specified ID
...
delete:
summary: Deletes the user with the specified ID
...
```
{% endcode %}
Any extra parameters defined at the operation level are used together with path-level parameters:
{% code lineNumbers="true" %}
```yaml
paths:
/users/{id}:
parameters:
- in: path
name: id
schema:
type: integer
required: true
description: The user ID.
# GET/users/{id}?metadata=true
get:
summary: Gets a user by ID
# Note we only define the query parameter, because the {id} is defined at the path level.
parameters:
- in: query
name: metadata
schema:
type: boolean
required: false
description: If true, the endpoint returns only the user metadata.
responses:
'200':
description: OK
```
{% endcode %}
Specific path-level parameters can be overridden on the operation level, but cannot be removed.
{% code lineNumbers="true" %}
```yaml
paths:
/users/{id}:
parameters:
- in: path
name: id
schema:
type: integer
required: true
description: The user ID.
# DELETE /users/{id} - uses a single ID.
# Reuses the {id} parameter definition from the path level.
delete:
summary: Deletes the user with the specified ID.
responses:
'204':
description: User was deleted.
# GET /users/id1,id2,id3 - uses one or more user IDs.
# Overrides the path-level {id} parameter.
get:
summary: Gets one or more users by ID.
parameters:
- in: path
name: id
required: true
description: A comma-separated list of user IDs.
schema:
type: array
items:
type: integer
minItems: 1
explode: false
style: simple
responses:
'200':
description: OK
```
{% endcode %}
#### **Common Parameters for Various Paths**
Different API paths may have common parameters, such as pagination parameters. You can define common parameters under parameters in the global `components` section and reference them elsewhere via `$ref`.
{% code lineNumbers="true" %}
```yaml
components:
parameters:
offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it.
# Not necessarily the same as the parameter name.
in: query
name: offset
required: false
schema:
type: integer
minimum: 0
description: The number of items to skip before starting to collect the result set.
limitParam:
in: query
name: limit
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 20
description: The numbers of items to return.
paths:
/users:
get:
summary: Gets a list of users.
parameters:
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: OK
/teams:
get:
summary: Gets a list of teams.
parameters:
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: OK
```
{% endcode %}
Note that the parameters defined in `components` are not parameters applied to all operations — they are simply global definitions that can be easily re-used.
### Parameter Dependencies
OpenAPI 3.0 does not support parameter dependencies and mutually exclusive parameters. There is an open feature request at . What you can do is document the restrictions in the parameter description and define the logic in the 400 Bad Request response. For example, consider the `/report` endpoint that accepts either a relative date range (`rdate`) or an exact range (`start_date`+`end_date`):
{% code lineNumbers="true" %}
```yaml
GET /report?rdate=Today
GET /report?start_date=2016-11-15&end_date=2016-11-20
```
{% endcode %}
You can describe this endpoint as follows:
{% code lineNumbers="true" %}
```yaml
paths:
/report:
get:
parameters:
- name: rdate
in: query
schema:
type: string
description: >
A relative date range for the report, such as `Today` or `LastWeek`.
For an exact range, use `start_date` and `end_date` instead.
- name: start_date
in: query
schema:
type: string
format: date
description: >
The start date for the report. Must be used together with `end_date`.
This parameter is incompatible with `rdate`.
- name: end_date
in: query
schema:
type: string
format: date
description: >
The end date for the report. Must be used together with `start_date`.
This parameter is incompatible with `rdate`.
responses:
'400':
description: Either `rdate` or `start_date`+`end_date` are required.
```
{% endcode %}
### References
[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#parameterObject)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://eazyapi-1.gitbook.io/docs/open-api-guide/describing-parameters.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.