From 33e5b98cd71b31d1370c0995df49bf04c6419c16 Mon Sep 17 00:00:00 2001 From: Kristine Hahn Date: Sat, 10 Jun 2017 23:40:10 -0700 Subject: [PATCH 1/4] edit Parameter Locations and its Fixed Fields --- versions/3.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 2c9c85c356..274db329af 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -954,7 +954,7 @@ Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). ##### Parameter Locations -There are four possible parameter locations (as specified with the `in` field): +There are four possible parameter locations specified by 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 [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. @@ -964,7 +964,7 @@ There are four possible parameter locations (as specified with the `in` field): ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. +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 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`. From 44acc4f9844ec4834887183b50d18c5da2423fee Mon Sep 17 00:00:00 2001 From: Kristine Hahn Date: Sun, 11 Jun 2017 06:52:18 -0700 Subject: [PATCH 2/4] more edits to Parameter Locations --- versions/3.0.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 274db329af..a0e92c9118 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -972,25 +972,25 @@ Field Name | Type | Description 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 [`schema`](#parameterSchema) and [`style`](#parameterStyle) can be used to describe the structure and syntax of the parameter. +For simplicity, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. Field Name | Type | Description ---|:---:|--- -style | `string` | Describes how the parameter value will be serialized depending on type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`. -explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. +style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`. +explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`. schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter. -example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the the example provided by the schema. To represent examples of media types that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. +example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary. examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. -For more complex scenarios the [`content`](#parameterContent) property can be used to define the media type and schema of the parameter. +For complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. Field Name | Type | Description ---|:---:|--- -content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value is used to describe it. The map MUST only contain one entry. +content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry. ##### Style Values From 81d2ed851187f1fc77a6474e41862935f4889553 Mon Sep 17 00:00:00 2001 From: Kristine Hahn Date: Sun, 11 Jun 2017 08:29:04 -0700 Subject: [PATCH 3/4] change per MR's and change mutually exclusive to > of 2x --- versions/3.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index a0e92c9118..20ae0c3c0e 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -972,7 +972,7 @@ Field Name | Type | Description 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 simplicity, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. +For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. Field Name | Type | Description ---|:---:|--- @@ -980,10 +980,10 @@ Field Name | Type | Description explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`. schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter. -example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary. -examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. +example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` object is mutually exclusive of the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary. +examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` object is mutually exclusive of the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. -For complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. +For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. From d8929f0d3d16dc25fd9ae325dbfe82d35f8270c1 Mon Sep 17 00:00:00 2001 From: Kristine Hahn Date: Wed, 14 Jun 2017 11:24:13 -0700 Subject: [PATCH 4/4] clarify behavior is n/a --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 20ae0c3c0e..3af17c50e7 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -969,7 +969,7 @@ Field Name | Type | Description 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 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, and if behavior is `n/a` (cannot be serialized), 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 [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter.