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:

paths:
  /users/{userId}:
    get:
      summary: Gets a user by ID.
      parameters:
        - in: path
          name: userId
          type: integer
          required: true
          description: Numeric ID of the user to get.

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

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: bodyparameter, 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 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. Some elements of the specification support the example or examples 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 and maxItems 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.

PreviousPaths and OperationsNextDescribing Request Body

Last updated