Describing Parameters
In Swagger, API operation parameters are defined under the parameters
section in the operation definition. Each parameter has name
, value type
(for primitive value parameters) or schema
(for request body), and optional description
. Here is an example:
Note that parameters
is an array, so, in YAML, each parameter definition must be listed with a dash (-
) in front of it.
Parameter Types
Swagger distinguishes between the following parameter types based on the parameter location. The location is determined by the parameter’s in
key, for example, in: query
or in: path
.
- query parameters, such as
/users?role=admin
- path parameters, such as
/users/{id}
- header parameters, such as
X-MyHeader: Value
- body parameters that describe the body of POST, PUT and PATCH requests (see Describing Request Body)
- form parameters – a variety of body parameters used to describe the payload of requests with
Content-Type
ofapplication/x-www-form-urlencoded
andmultipart/form-data
(the latter is typically used for file uploads)
Query Parameters
Query parameters are the most common type of parameters. They appear at the end of the request URL after a question mark (?
), with different name=value
pairs separated by ampersands (&
). Query parameters can be required and optional.
Use in: query
to denote query parameters:
Query parameters only support primitive types. You can have an array
, but the items
must be a primitive value type. Objects are not supported.
Note: To describe API keys passed as query parameters, use a security definition instead. See API Keys.
Path Parameters
Path parameters are components of a URL path that can vary. They are typically used to point to a specific resource within a collection, such as a user identified by ID. A URL can have several path parameters, each denoted with curly braces { }
.
Each path parameter must be substituted with an actual value when the client makes an API call. In Swagger, a path parameter is defined using in: path
and other attributes as necessary. The parameter name must be the same as specified in the path. Also, remember to add required: true
, because path parameters are always required. Here is an example for GET /users/{id}
:
Path parameters can be multi-valued, such as GET /users/12,34,56
. This is achieved by specifying the parameter type as array
. See Array and Multi-Value Parameters below.
Header Parameters
An API call may require that custom headers be sent with an HTTP request. Swagger lets you define custom request headers as in: header
parameters. For example, suppose, a call to GET /ping
requires the X-Request-ID
header:
In Swagger, you would define this operation as follows:
In a similar way, you can define custom response headers.
Note: Swagger specification has special keywords for some headers:
Header | Swagger Keywords | For more information, see... |
---|---|---|
Content-Type |
consumes (request content type)produces (response content type) |
MIME Types |
Accept |
produces |
MIME Types |
Authorization |
securityDefinitions , security |
Authentication |
Form Parameters
Form parameters are used to describe the payload of requests with Content-Type
of:
application/x-www-form-urlencoded
(used to POST primitive values and arrays of primitive values).multipart/form-data
(used to upload files or a combination of files and primitive data).
That is, the operation’s consumes
property must specify one of these content types. Form parameters are defined as in: formData
. They can only be primitives (strings, numbers, booleans) or arrays of primitives (meaning you cannot use a $ref
as the items
value). Also, form parameters cannot coexist with the in: body
parameter, because formData
is a specific way of describing the body. To illustrate form parameters, consider an HTML POST form:
This form POSTs data to the form’s endpoint:
In Swagger, you can describe the endpoint as follows:
To learn how to define form parameters for file uploads, see File Upload.
Required and Optional Parameters
By default, Swagger 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.
Default Parameter Values
You can use the default
key 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:
Assuming offset defaults to 0 and limit defaults to 20 and ranges from 0 to 100, you would define these parameters as:
Common Mistakes
There are two common mistakes when using the default
keyword:
- Using
default
withrequired
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. Some elements of the specification support theexample
orexamples
keyword for this purpose.
Enum Parameters
The enum
keyword allows you to restrict a parameter value to a fixed set of values. The enum values must be of the same type as the parameter type
.
More info: Defining an Enum.
Array and Multi-Value Parameters
Path, query, header and form parameters can accept a list of values, for example:
A multi-value parameter must be defined with type: array
and the appropriate collectionFormat
.
collectionFormat
specifies the array format (a single parameter with multiple parameter or multiple parameters with the same name) and the separator for array items.
collectionFormat | Description | Example |
---|---|---|
csv (default) |
Comma-separated values. | foo,bar,baz |
ssv |
Space-separated values. | foo bar baz |
tsv |
Tab-separated values. | "foo\tbar\tbaz" |
pipes |
Pipe-separated values. | foo|bar|baz |
multi |
Multiple parameter instances rather than multiple values. This is only supported for the in: query and in: formData parameters. |
foo=value&foo=another_value |
Additionally, you can:
- use
minItems
andmaxItems
to control the size of the array, - enforce
uniqueItems
, - restrict the array items to a fixed set of
enum
values.
For example:
You can also specify the default array that the server will use if this parameter is omitted:
Constant Parameters
You can define a constant parameter as a required parameter with only one possible value:
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. 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.
Parameters Without a Value
Query string and form data parameters may only have a name and no value:
Use allowEmptyValue
to describe such parameters:
Common Parameters
Common Parameters for All Methods of a Path
Parameters can be defined under a path itself, in this case, the parameters exist in all operations described under this path. A typical example is the GET/PUT/PATCH/DELETE operations that manipulate the same resource accessed via a path parameter.
Any extra parameters defined at the operation level are used together with path-level parameters:
Specific path-level parameters can be overridden on the operation level, but cannot be removed.
Common Parameters in Different Paths
Different API paths may have some common parameters, such as pagination parameters. You can define common parameters in the global parameters
section and reference them in individual operations via $ref
.
Note that the global parameters
are not parameters applied to all operations — they are simply global definitions that can be easily re-used.
Parameter Dependencies
Swagger does not support parameter dependencies and mutually exclusive parameters. There is an open feature request at https://github.com/OAI/OpenAPI-Specification/issues/256. 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
):
You can describe this endpoint as follows:
FAQ
When should I use “type” vs “schema”?
schema is only used with in: body
parameters. Any other parameters expect a primitive type, such as type: string
, or an array
of primitives.
Can I have an object as a query parameter?
This is possible in OpenAPI 3.0, but not in 2.0.
Did not find what you were looking for? Ask the community
Found a mistake? Let us know