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:

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Gets a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          type: integer
9
          required: true
10
          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, 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 of application/x-www-form-urlencoded and multipart/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.

1
GET /pets/findByStatus?status=available
2
GET /notes?offset=100&limit=50

Use in: query to denote query parameters:

1
parameters:
2
  - in: query
3
    name: offset
4
    type: integer
5
    description: The number of items to skip before starting to collect the result set.
6
  - in: query
7
    name: limit
8
    type: integer
9
    description: The numbers of items to return.

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 { }.

1
GET /users/{id}
2
GET /cars/{carId}/drivers/{driverId}

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}:

1
paths:
2
  /users/{id}:
3
    get:
4
      parameters:
5
        - in: path
6
          name: id   # Note the name is the same as in the path
7
          required: true
8
          type: integer
9
          minimum: 1
10
          description: The user ID.
11
        responses:
12
          200:
13
            description: OK

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:

1
GET /ping HTTP/1.1
2
Host: example.com
3
X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac

In Swagger, you would define this operation as follows:

1
paths:
2
  /ping:
3
    get:
4
      summary: Checks if the server is alive.
5
      parameters:
6
        - in: header
7
          name: X-Request-ID
8
          type: string
9
          required: true

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:

1
<form action="http://example.com/survey" method="post">
2
  <input type="text" name="name" />
3
  <input type="number" name="fav_number" />
4
  <input type="submit" />
5
</form>

This form POSTs data to the form’s endpoint:

1
POST /survey HTTP/1.1
2
Host: example.com
3
Content-Type: application/x-www-form-urlencoded
4
Content-Length: 29
5

6
name=Amy+Smith&fav_number=321

In Swagger, you can describe the endpoint as follows:

1
paths:
2
  /survey:
3
    post:
4
      summary: A sample survey.
5
      consumes:
6
        - application/x-www-form-urlencoded
7
      parameters:
8
        - in: formData
9
          name: name
10
          type: string
11
          description: A person's name.
12
        - in: formData
13
          name: fav_number
14
          type: number
15
          description: A person's favorite number.
16
      responses:
17
        200:
18
          description: OK

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.

1
parameters:
2
  - in: path
3
    name: userId
4
    type: integer
5
    required: true # <----------
6
    description: Numeric ID of the user to get.

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:

1
GET /users
2
GET /users?offset=30&limit=10

Assuming offset defaults to 0 and limit defaults to 20 and ranges from 0 to 100, you would define these parameters as:

1
parameters:
2
  - in: query
3
    name: offset
4
    type: integer
5
    required: false
6
    default: 0
7
    minimum: 0
8
    description: The number of items to skip before starting to collect the result set.
9
  - in: query
10
    name: limit
11
    type: integer
12
    required: false
13
    default: 20
14
    minimum: 1
15
    maximum: 100
16
    description: The numbers of items to return.

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.

1
- in: query
2
  name: status
3
  type: string
4
  enum: [available, pending, sold]

More info: Defining an Enum.

Array and Multi-Value Parameters

Path, query, header and form parameters can accept a list of values, for example:

1
GET /users/12,34,56,78
2
GET /resource?param=value1,value2,value3
3
GET /resource?param=value1&param=value2&param=value3
4

5
POST /resource
6
param=value1&param=value2

A multi-value parameter must be defined with type: array and the appropriate collectionFormat.

1
# color=red,black,white
2
parameters:
3
  - in: query
4
    name: color
5
    type: array
6
    collectionFormat: csv
7
    items:
8
      type: string

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:

1
- in: query
2
  name: color
3
  required: false
4
  type: array
5
  minItems: 1
6
  maxItems: 5
7
  uniqueItems: true
8
  items:
9
    type: string
10
    enum:
11
      [
12
        black,
13
        white,
14
        gray,
15
        red,
16
        pink,
17
        orange,
18
        yellow,
19
        green,
20
        blue,
21
        purple,
22
        brown,
23
      ]

You can also specify the default array that the server will use if this parameter is omitted:

1
- in: query
2
  name: sort
3
  required: false
4
  type: array
5
  items:
6
    type: string
7
  default: ["-modified", "+id"]

Constant Parameters

You can define a constant parameter as a required parameter with only one possible value:

1
- required: true
2
  enum: [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:

1
GET /foo?metadata
2

3
POST /something
4
foo&bar&baz

Use allowEmptyValue to describe such parameters:

1
- in: query
2
  name: metadata
3
  required: true
4
  type: boolean
5
  allowEmptyValue: true # <-----

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.

1
paths:
2
  /user/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        type: integer
7
        required: true
8
        description: The user ID.
9

10
    get:
11
      summary: Gets a user by ID.
12
      ...
13
    patch:
14
      summary: Updates an existing user with the specified ID.
15
      ...
16
    delete:
17
      summary: Deletes the user with the specified ID.
18
      ...

Any extra parameters defined at the operation level are used together with path-level parameters:

1
paths:
2
  /users/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        type: integer
7
        required: true
8
        description: The user ID.
9

10
    # GET/users/{id}?metadata=true
11
    get:
12
      summary: Gets a user by ID.
13
      # Note we only define the query parameter, because the {id} is defined at the path level.
14
      parameters:
15
        - in: query
16
          name: metadata
17
          type: boolean
18
          required: false
19
          description: If true, the endpoint returns only the user metadata.
20
      responses:
21
        200:
22
          description: OK

Specific path-level parameters can be overridden on the operation level, but cannot be removed.

1
paths:
2
  /users/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        type: integer
7
        required: true
8
        description: The user ID.
9

10
    # DELETE /users/{id} - uses a single ID.
11
    # Reuses the {id} parameter definition from the path level.
12
    delete:
13
      summary: Deletes the user with the specified ID.
14
      responses:
15
        204:
16
          description: User was deleted.
17

18
    # GET /users/id1,id2,id3 - uses one or more user IDs.
19
    # Overrides the path-level {id} parameter.
20
    get:
21
      summary: Gets one or more users by ID.
22
      parameters:
23
        - in: path
24
          name: id
25
          required: true
26
          description: A comma-separated list of user IDs.
27
          type: array
28
          items:
29
            type: integer
30
          collectionFormat: csv
31
          minItems: 1
32
      responses:
33
        200:
34
          description: OK

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.

1
parameters:
2
  offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it.
3
    # Not necessarily the same as the parameter name.
4
    in: query
5
    name: offset
6
    required: false
7
    type: integer
8
    minimum: 0
9
    description: The number of items to skip before starting to collect the result set.
10
  limitParam:
11
    in: query
12
    name: limit
13
    required: false
14
    type: integer
15
    minimum: 1
16
    maximum: 50
17
    default: 20
18
    description: The numbers of items to return.
19
paths:
20
  /users:
21
    get:
22
      summary: Gets a list of users.
23
      parameters:
24
        - $ref: "#/parameters/offsetParam"
25
        - $ref: "#/parameters/limitParam"
26
      responses:
27
        200:
28
          description: OK
29
  /teams:
30
    get:
31
      summary: Gets a list of teams.
32
      parameters:
33
        - $ref: "#/parameters/offsetParam"
34
        - $ref: "#/parameters/limitParam"
35
      responses:
36
        200:
37
          description: OK

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):

1
GET /report?rdate=Today
2
GET /report?start_date=2016-11-15&end_date=2016-11-20

You can describe this endpoint as follows:

1
paths:
2
  /report:
3
    get:
4
      parameters:
5
        - name: rdate
6
          in: query
7
          type: string
8
          description: >
9
            A relative date range for the report, such as `Today` or `LastWeek`.
10
            For an exact range, use `start_date` and `end_date` instead.
11
        - name: start_date
12
          in: query
13
          type: string
14
          format: date
15
          description: >
16
            The start date for the report. Must be used together with `end_date`.
17
            This parameter is incompatible with `rdate`.
18
        - name: end_date
19
          in: query
20
          type: string
21
          format: date
22
          description: >
23
            The end date for the report. Must be used together with `start_date`.
24
            This parameter is incompatible with `rdate`.
25
      responses:
26
        400:
27
          description: Either `rdate` or `start_date`+`end_date` are required.

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