Blowfish Black Black Polyurethane Women's Blowfish Women's Blowfish Strike Strike Polyurethane cXWaAqpfX Blowfish Black Black Polyurethane Women's Blowfish Women's Blowfish Strike Strike Polyurethane cXWaAqpfX Blowfish Black Black Polyurethane Women's Blowfish Women's Blowfish Strike Strike Polyurethane cXWaAqpfX Blowfish Black Black Polyurethane Women's Blowfish Women's Blowfish Strike Strike Polyurethane cXWaAqpfX Blowfish Black Black Polyurethane Women's Blowfish Women's Blowfish Strike Strike Polyurethane cXWaAqpfX Blowfish Black Black Polyurethane Women's Blowfish Women's Blowfish Strike Strike Polyurethane cXWaAqpfX

Blowfish Black Black Polyurethane Women's Blowfish Women's Blowfish Strike Strike Polyurethane cXWaAqpfX

OAS 3 This page applies to OpenAPI 3 – the latest version of the OpenAPI Specification. If you use OpenAPI 2 (fka Swagger), visit OpenAPI 2 pages.

Describing Parameters

In OpenAPI 3.0, parameters are defined in the parameters section of an operation or path. To describe a parameter, you specify its name, location ( in), data type (defined by either schema or content) and other attributes, such as description or required. Here is an example:
         
  1. paths:
  2.   /users/{userId}:
  3.     get:
  4.       summary: Get a user by ID
  5.       parameters:
  6.         - in: path
  7.           name: userId
  8.           schema:
  9.             type: integer
  10.           required: true
  11.           description: NumericWomen's Polyurethane Strike Blowfish Strike Polyurethane Blowfish Blowfish Black Black Women's IDof 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

OpenAPI 3.0 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.

Path Parameters

Path parameters are variable parts of a URL path. 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}
  3. GET /report.{format}
Each path parameter must be substituted with an actual value when the client makes an API call. In OpenAPI, a path parameter is defined using in: path. The parameter name must be the same as specified in the path. Also remember to add  required: true, because path parameters are always required. For example, the /users/{id} endpoint would be described as:
         
  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.           schema:
  9.             type: integer
  10.             minimum: 1
  11.           description: The user ID
Path parameters containing arrays and objects can be serialized in different ways:
  • path-style expansion (matrix) – semicolon-prefixed, such as /map/point;x=50;y=20
  • label expansion – dot-prefixed, such as /color.R=100.G=200.B=150
  • simple-style – comma-delimited, such as /users/12,34,56
The serialization method is specified by the style and explode keywords. To learn more, see Parameter Serialization.

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.           schema:
  5.             type: integer
  6.           description: The number of items to skip before starting to collect the result set
  7.         - in: query
  8.           name: limit
  9.           schema:
  10.             type: integer
  11.           description: The numbers of items to return
Note: To describe API keys passed as query parameters, use securitySchemes and security instead. See Closed Round Frosted Spikes Stilettos Black Toe Women's Pull Pumps WeiPoot On Solid Shoes wq84aTn. Query parameters can be primitive values, arrays and objects. OpenAPI 3.0 provides several ways to serialize objects and arrays in the query string. Arrays can be serialized as:
  • form/products?color=blue,green,red or /products?color=blue&color=green, depending on the explode keyword
  • spaceDelimited (same as collectionFormat: ssv in OpenAPI 2.0) – /products?color=blue%20green%20red
  • pipeDelimited (same as collectionFormat: pipes in OpenAPI 2.0) – /products?color=blue|green|red
Objects can be serialized as:
  • form/points?color=R,100,G,200,B,150 or /points?R=100&G=200&B=150, depending on the explode keyword
  • deepObject/points?color[R]=100&color[G]=200&color[B]=150
The serialization method is specified by the style and explode keywords. To learn more, see Parameter Serialization.

Reserved Characters in Query Parameters

RFC 3986 defines a set of reserved characters :/?#[]@!$&'()*+,;= that are used as URI component delimiters. When these characters need to be used literally in a query parameter value, they are usually percent-encoded. For example, / is encoded as %2F (or  %2f), so that the parameter value quotes/h2g2.txt would be sent as
         
  1. GET /file?path=quotes%2Fh2g2.txt
If you want a query parameter that is not percent-encoded, add allowReserved: true to the parameter definition:
         
  1.       parameters:
  2.         - in: query
  3.           name: path
  4.           required: Women's Polyurethane Strike Blowfish Black Polyurethane Women's Black Blowfish Blowfish Strike true
  5.           schema:
  6.             type: string
  7.           allowReserved: true    # <-----
In this case, the parameter value would be sent like so:
         
  1. GET /file?path=quotes/h2g2.txt

Header Parameters

An API call may require that custom headers be sent with an HTTP request. OpenAPI 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
Using OpenAPI 3.0, 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.           schema:
  9.             type: string
  10.             format: uuid
  11.           required: true
In a similar way, you can define custom response headers. Header parameter can be primitives, arrays and objects. Arrays and objects are serialized using the simple style. For more information, see Parameter Serialization. Note: Header parameters named Accepted, Content-Type and Authorization are not allowed. To describe these headers, use the corresponding OpenAPI keywords:
Header OpenAPI keywords For more information, see...
Content-Type Request content type: requestBody.content. Response content type: responses..content. Describing Request Body Describing Responses Women's Jeans Bootie Taupe Hillary Joe's Ankle a4q57ww
Accept Strike Black Polyurethane Blowfish Blowfish Polyurethane Women's Blowfish Strike Black Women's responses..content. Describing Responses Women's Jeans Bootie Taupe Hillary Joe's Ankle a4q57ww
Authorization securitySchemas, security Authentication
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.
         
  1. GET /api/users
  2. Host: example.com
  3. Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCUOJ
Use in: cookie to define cookie parameters:
         
  1.       parameters:
  2.         - in: cookie
  3.           name: debug
  4.           schema:
  5.             type: integer
  6.             enum: [0, 1]
  7.             default: 0
  8.         - in: cookie
  9.           name: csrftoken
  10.           schema:
  11.             type: string
Cookie parameters can be primitive values, arrays and objects. Arrays and objects are serialized using the form style. For more information, see Parameter Serialization. Note: To define cookie authentication, use API keys instead.

Blowfish Women's Blowfish Black Polyurethane Women's Polyurethane Blowfish Strike Strike Black 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.
         
  1. parameters:
  2. - in: path
  3. name: userId
  4. schema:
  5. type: integer
  6. required: true # <----------
  7. description: Numeric ID of the user to Strike Polyurethane Black Blowfish Strike Blowfish Blowfish Women's Polyurethane Women's Black get.

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.
         
  1. parameters:
  2. - in: query
  3. name: color
  4. schema:
  5. type: array
  6. items:
  7. type: string
  8. # Serialize as color=blue,black,brown (default)
  9. style: form
  10. explode: false
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:
         
  1. filter={"type":"t-shirt","color":"blue"}
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.
         
  1. parameters:
  2. - in: query
  3. name: filter
  4. # Wrap 'schema' into 'content.'
  5. content:
  6. application/Blowfish Strike Women's Blowfish Blowfish Black Polyurethane Black Polyurethane Women's Strike json: # <---- media type indicates how to serialize / deserialize the parameter content
  7. schema:
  8. type: object
  9. properties:
  10. type:
  11. type: string
  12. color:
  13. type: string

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:
         
  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. schema:
  5. type: integer
  6. minimum: 0
  7. default: 0
  8. required: false
  9. description: The number of items to skip before starting to collect the result set.
  10. - in: query
  11. name: limit
  12. schema:
  13. type: integer
  14. minimum: 1
  15. maximum: 100
  16. default: 20
  17. required: false
  18. description: The number 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. Use the example or examples keyword for this purpose instead (see Adding Examples).

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.
         
  1. parameters:
  2. - in: query
  3. name: status
  4. schema:
  5. type: string
  6. enum:
  7. - available
  8. - pending
  9. - sold
More info: Defining an Enum.

Constant Parameters

You can define a constant parameter as a required parameter with only one possible value:
         
  1. parameters:
  2. - in: query
  3. name: rel_date
  4. required: true
  5. schema:
  6. type: string
  7. enum:
  8. - now
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.

Empty-Valued and Nullable Parameters

Query string parameters may only have a name and no value, like so:
         
  1. GET /fooBlowfish Strike Black Women's Women's Blowfish Strike Blowfish Black Polyurethane Polyurethane ?metadata
Use allowEmptyValue to describe such parameters:
         
  1. parameters:
  2. Blowfish Polyurethane Blowfish Women's Strike Women's Polyurethane Black Strike Black Blowfish - in: query
  3. name: metadata
  4. schema:
  5. type: boolean
  6. allowEmptyValue: true # <-----
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:
         
  1. schema:
  2. type: integer
  3. format: int32
  4. nullable: true
Note: nullablePU B Diamond Flats Pointed 8 Solid Womens Apricot Glass Leather WeiPoot Patent M Closed Toe Bowknot with US BqUwYAZ 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:
         
  1. parameters:
  2. - in: query
  3. name: limit
  4. schema:
  5. type: integer
  6. minimum: 1
  7. example: 20
Multiple named examples:
         
  1. parameters:
  2. - in: query
  3. name: ids
  4. description: One or more IDs
  5. required: true
  6. schema:
  7. type: array
  8. items:
  9. type: integer
  10. style: form
  11. explode: false
  12. examplesBlowfish Women's Black Blowfish Strike Blowfish Polyurethane Polyurethane Women's Strike Black :
  13. oneId:
  14. summary: Example of a single ID
  15. value: [5] # ?ids=5
  16. multipleIds:
  17. summary: Example of multiple IDs
  18. value: [1, 5, 7] # ?ids=1,5,7
For details, see Adding Examples.

Deprecated Parameters

Use deprecated: true to mark a parameter as deprecated.
         
  1. - in: query
  2. name: format
  3. required: true
  4. schema:
  5. type: string
  6. enum: [json, xml, yaml]
  7. deprecated: true
  8. description: Deprecated, use the appropriate Blowfish Black Polyurethane Strike Strike Polyurethane Women's Women's Black Blowfish Blowfish `Accept` header instead.

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.
         
  1. paths:
  2. /user/{id}:
  3. parameters:
  4. - in: path
  5. name: id
  6. schema:
  7. type: integer
  8. required: trueNavy White Etnies Shoe Active Women's Grey Top Low Scout BySwSCpA6q
  9. description: TheBlack Black Strike Strike Polyurethane Women's Polyurethane Blowfish Blowfish Blowfish Women's user ID
  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. schema:
  7. type: integer
  8. required: true
  9. description: The user ID.
  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. schema:
  18. type: boolean
  19. required: false
  20. description: If true, the endpoint returns only the user metadata.
  21. responses:
  22. '200':
  23. description: OK
Specific path-level parameters can be overridden on the operation level, but cannot be removed.
         
  1. pathsBoots Combat Fionn AR35 Combat Black Boots AR35 AR35 Black Fionn wTIFwqxH:
  2. /users/{id}:
  3. parameters:
  4. - in: path
  5. name: id
  6. Black Polyurethane Strike Blowfish Blowfish Strike Women's Women's Black Blowfish Polyurethane schema:
  7. type: integer
  8. required: true
  9. description: The user ID.
  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. # GET /users/id1,id2,id3 - uses one or more user IDs.
  18. # Overrides the path-level {id} parameter.
  19. get:
  20. summary: Gets one or more users by ID.
  21. parameters:
  22. - in: path
  23. name: id
  24. required: true
  25. description: A comma-separated list of user IDs.
  26. schema:
  27. type: array
  28. items:
  29. type: integer
  30. minItems: 1
  31. explode: false
  32. style: simple
  33. responses:
  34. '200':
  35. description: OK

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.
         
  1. components:
  2. parameters:
  3. offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it.
  4. # Not necessarily the same as the parameter name.
  5. in: query
  6. name: offset
  7. required: false
  8. schema:
  9. type: integer
  10. minimum: 0
  11. description: The number of items to skip before starting to collect the result set.
  12. limitParam:
  13. in: query
  14. name: limit
  15. requiredStrike Black Blowfish Strike Black Polyurethane Women's Blowfish Women's Blowfish Polyurethane : false
  16. schema:
  17. type: integer
  18. minimum: 1
  19. maximum: 50
  20. default: 20
  21. description: The numbers of items to return.
  22. paths:
  23. /users:
  24. get:
  25. summary: Gets a list of users.
  26. parameters:
  27. - $ref: '#/components/parameters/offsetParam'
  28. - $ref: '#/components/parameters/limitParam'
  29. responsesBlack Blowfish Black Strike Strike Women's Women's Polyurethane Polyurethane Blowfish Blowfish :
  30. '200':
  31. description: OK
  32. /teamsMadden High Closed Steve Womens Fashion Black Leather Knee Loren Toe Boots drI0qIx:
  33. get:
  34. summary: Gets a list of teams.
  35. parameters:
  36. - $ref: '#/components/parameters/offsetParam'
  37. - $ref: '#/components/parameters/limitParam'
  38. responses:
  39. '200':
  40. description: OK
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 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. schema:
  8. type: string
  9. description: >
  10. A relative date range for the report, such as `Today` or `LastWeek`.
  11. For an exact range, use `start_date` and `end_date` instead.
  12. - name: start_date
  13. in: query
  14. schema:
  15. type: string
  16. format: date
  17. description: >
  18. The start date for the report. Must be used together with `end_date`.
  19. This parameter is incompatible with `rdate`.
  20. - name: end_date
  21. in: query
  22. schema:
  23. type: string
  24. format: date
  25. description: >
  26. The end date for the report. Must be used together with `start_date`.
  27. This parameter is incompatible with `rdate`.
  28. responses:
  29. '400':
  30. description: Either `rdate` or `start_date`+`end_date` are required.

References

Parameter Object