diff --git a/versions/3.0.md b/versions/3.0.md index bb9ef288dc..8f1deebb48 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -735,11 +735,11 @@ Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). -There are four possible parameter types. -* Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. -* Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. -* Header - Custom headers that are expected as part of the request. Note that [RFC 7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. -* Cookie - Used to pass a specific cookie value to the API. +There are four possible parameter locations (as specified with the `in` field): +* path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. +* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. +* header - Custom headers that are expected as part of the request. Note that [RFC 7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. +* cookie - Used to pass a specific cookie value to the API. ##### Fixed Fields @@ -748,9 +748,9 @@ Field Name | Type | Description name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*. in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path" or "cookie". description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. +required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameterIn) is "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. -allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](# @parameterStyle) is used, if behavior is `n/a`, the value of `allowEmptyValue` SHALL be ignored. +allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](#parameterStyle) is used, if behavior is `n/a`, the value of `allowEmptyValue` SHALL be ignored. The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a [`style`](#parameterStyle) and [`schema`](#parameterSchema) can be used to describe the structure and syntax of the parameter.