From 65b1d999c8f46b3e0a4d3e781659901c0d3d10da Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 30 Sep 2016 11:04:20 -0400 Subject: [PATCH 01/10] URI Template support in parameters --- versions/3.0.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index 9acd51bc98..ccbfc013e2 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -647,6 +647,9 @@ Field Name | Type | Description 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`. deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage. schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter. +escape | `boolean` | Determines whether the parameter value should have unallowed characters percent-encoded based the parameter location. The default value is `true`. +style | `string` | Determines rendering rules based on [RFC 6570](https://tools.ietf.org/html/rfc6570). Valid values include "matrix", "label", "segment", "simple". The style is only used when `in` has the value `path`. "matrix" refers to what RFC6570 calls "path-style". Default value is "simple". +explode | `boolean` | Indicates if the parameter values should rendered using the rules of the explode operator as defined in [RFC 6570](https://tools.ietf.org/html/rfc6570#section-2.2). Default value is `false`. ##### Patterned Fields From 5da76a4e7bf63d400873527adeb8a8a7a08a540c Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 7 Oct 2016 20:50:56 -0700 Subject: [PATCH 02/10] Introduced prefix and separator --- versions/3.0.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index ccbfc013e2..7903ab2feb 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -647,16 +647,25 @@ Field Name | Type | Description 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`. deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage. schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter. -escape | `boolean` | Determines whether the parameter value should have unallowed characters percent-encoded based the parameter location. The default value is `true`. -style | `string` | Determines rendering rules based on [RFC 6570](https://tools.ietf.org/html/rfc6570). Valid values include "matrix", "label", "segment", "simple". The style is only used when `in` has the value `path`. "matrix" refers to what RFC6570 calls "path-style". Default value is "simple". +escape | `boolean` | Determines whether the parameter value should have unallowed characters percent-encoded based the parameter location. This property only applies to parameters with an `in` value of `query`. The default value is `true`. +style | `string` | Defines a character to prefix each parameter value. Valid values include [;.]. Where no separator is specified and a parameter value is an array, then a comma will be used as the default separator. +style | `string` | Defines a character used to separate the values of parameters that are lists and maps. Value values include [;.]. Where no separator is specified and a parameter value is an array, then a comma will be used as the default separator. explode | `boolean` | Indicates if the parameter values should rendered using the rules of the explode operator as defined in [RFC 6570](https://tools.ietf.org/html/rfc6570#section-2.2). Default value is `false`. - ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details. +##### Parameter Value Rendering Examples + +path | escape | prefix | separator | explode | Value | Output +---|:---:|---:|---:|---:|---:|---:| +/share/myfile{ext} | true | . | | false | jpg | /share/myfile.jpg +/registerwebhook?url={callback} | false | | | false | http://example.org/myreceiver | /registerwebhook?url=http://example.org/myreceiver +/letters?value={value} | true | | , | false | [a,b,c] | /letters?value=a,b,c +/letters?value={value} | true | | , | true | [a,b,c] | /letters?value=a&value=b,c + ##### Parameter Object Examples From 79f313d2697d604f3d37c929de9ff93aaed528b7 Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 18 Nov 2016 13:15:40 -0500 Subject: [PATCH 03/10] uri template stuff --- versions/3.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/3.0.md b/versions/3.0.md index d834251391..e6690d248e 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -758,6 +758,8 @@ path | escape | prefix | separator | explode | Value | Output /letters?value={value} | true | | , | false | [a,b,c] | /letters?value=a,b,c /letters?value={value} | true | | , | true | [a,b,c] | /letters?value=a&value=b,c + + This object can be extended with [Specification Extensions](#specificationExtensions). ##### Parameter Object Examples From 8cb7e267e98ac7a9c236c489d21d66423e159823 Mon Sep 17 00:00:00 2001 From: Darrel Date: Wed, 21 Dec 2016 11:40:36 -0500 Subject: [PATCH 04/10] Updates to style parameter --- versions/3.0.md | 51 ++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 26 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 701899f1e3..512ec0c5e9 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -748,7 +748,6 @@ 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 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`. deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage. -allowReserved | `boolean` | Determines whether the parameter value should allow reserved characters `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`. The content of the parameter is specified in one of two ways. By passing a schema and content-type, complex parameters may be serialized and passed: @@ -763,6 +762,8 @@ Field Name | Type | Description type | `string` | **Required.** The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"` or `"object"`. format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details. style | `string` | Describes how the parameter value will be serialized depending on the specified [`type`](#parameterType). +allowReserved | `boolean` | Determines whether the parameter value should allow reserved characters `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`. +explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`. items | [Items Object](#itemsObject) | **Required if [`type`](#parameterType) is "array".** Describes the type of items in the array. default | * | Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See http://json-schema.org/latest/json-schema-validation.html#anchor101. Unlike JSON Schema this value MUST conform to the defined [`type`](#parameterType) for this parameter. @@ -779,21 +780,18 @@ Field Name | Type | Description enum | [*] | See http://json-schema.org/latest/json-schema-validation.html#anchor76. multipleOf | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor14. -In order to support some of the commonly used parameter serializations, a set of `style` values are defined. +In order to support alternate ways of serializing parameters, a set of `style` values are defined. `style` | [`type`](#dataTypeType) | `in` | Comments ----------- | ------ | -------- | -------- -matrix | `string`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) -exploded-matrix | `array`, `object` | `path` | Exploded path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) +matrix | `string`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) label | `string`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) -exploded-label | `object` | `path`| Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) form | `string`, `array`, `object` | `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8) -exploded-form | `array`, `object` | `query` | Exploded form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8) -space-delimited | `array` | `query`,`path` | This option replaces `collectionFormat` equal to `ssv` -pipe-delimited | `array` | `query`,`path` | This option replaces `collectionFormat` equal to `pipes` -exploded-object | `object` | `query` | Provides a simple way of rendering nested objects using form parameters +comma-delimited | `array` | `query`, `path` | Comma separated array values. This option replaces `collectionFormat` equal to `csv`. +space-delimited | `array` | `query`, `path` | Space separated array values. This option replaces `collectionFormat` equal to `ssv`. +pipe-delimited | `array` | `query`, `path` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes`. +deep-object | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. -comma-delimited ??? Examples: Assuming a parameter named `value` with one of the following values: @@ -805,18 +803,17 @@ Assuming a parameter named `value` with one of the following values: ``` The following table shows examples of how those values would be rendered. -[`style`](#dataTypeFormat) | `empty` | `string` | `array` | `object` ------------ | ------ | -------- | -------- | -------- -matrix | ;value | ;value=hello | ;value=blue,black,brown | ;value=x,100,y200 -exploded-matrix | n/a | n/a | ;value=blue;value=black;value=brown | ;x=100;y=100 -label | . | .hello | .blue.black.brown | .x.100.y.200 -exploded-label | n/a | n/a | n/a | .x=100.y=200 -form | . | value=hello | value=blue,black,brown | value=x,100,y,200 -exploded-form | n/a | n/a | value=blue&value=black&value=brown | x=100&y=200 -space-delimited | n/a | n/a | blue%20black%20brown | x%20100%20y%20200 -pipe-delimited | n/a | n/a | blue\|black\|brown | x\|100\|y\|200 -exploded-object | n/a | n/a | n/a | person[name]=Bob&person[lastname]=Brown - +[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` +----------- | ------ | -------- | -------- | --------|------- +matrix | false | ;value | ;value=hello | ;value=blue,black,brown | ;value=x,100,y200 +matrix | true | n/a | n/a | ;value=blue;value=black;value=brown | ;x=100;y=100 +label | false | . | .hello | .blue.black.brown | .x.100.y.200 +label | true | n/a | n/a | n/a | .x=100.y=200 +form | false | . | value=hello | value=blue,black,brown | value=x,100,y,200 +form | true | n/a | n/a | value=blue&value=black&value=brown | x=100&y=200 +space-delimited | false | n/a | n/a | blue%20black%20brown | x%20100%20y%20200 +pipe-delimited | false | n/a | n/a | blue\|black\|brown | x\|100\|y\|200 +deep-object | true | n/a | n/a | n/a | person[name]=Bob&person[lastname]=Brown This object can be extended with [Specification Extensions](#specificationExtensions). @@ -837,7 +834,7 @@ A header parameter with an array of 64 bit integer numbers: "format": "int64" } }, - "collectionFormat": "csv" + "style": "comma-delimited" } ``` @@ -851,7 +848,7 @@ schema: items: type: integer format: int64 - collectionFormat: csv +style: comma-delimited ``` A path parameter of a string value: @@ -889,7 +886,8 @@ An optional query parameter of a string value, allowing multiple values by repea "type": "string" } }, - "collectionFormat": "multi" + "style": "form", + "explode": true } ``` @@ -902,7 +900,8 @@ schema: type: array items: type: string - collectionFormat: multi +style: form +explode: true ``` A form data with file type for a file upload: From 8c07f31af699c44cbfeffc1bfbd908288112938a Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 24 Jan 2017 13:11:35 -0500 Subject: [PATCH 05/10] Updates based on review --- versions/3.0.md | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 512ec0c5e9..cb9043b26e 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -762,8 +762,8 @@ Field Name | Type | Description type | `string` | **Required.** The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"` or `"object"`. format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details. style | `string` | Describes how the parameter value will be serialized depending on the specified [`type`](#parameterType). -allowReserved | `boolean` | Determines whether the parameter value should allow reserved characters `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`. -explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. +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`. +explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of parameters this property has no effect. allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`. items | [Items Object](#itemsObject) | **Required if [`type`](#parameterType) is "array".** Describes the type of items in the array. default | * | Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See http://json-schema.org/latest/json-schema-validation.html#anchor101. Unlike JSON Schema this value MUST conform to the defined [`type`](#parameterType) for this parameter. @@ -787,33 +787,34 @@ In order to support alternate ways of serializing parameters, a set of `style` v matrix | `string`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) label | `string`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) form | `string`, `array`, `object` | `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8) -comma-delimited | `array` | `query`, `path` | Comma separated array values. This option replaces `collectionFormat` equal to `csv`. -space-delimited | `array` | `query`, `path` | Space separated array values. This option replaces `collectionFormat` equal to `ssv`. -pipe-delimited | `array` | `query`, `path` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes`. -deep-object | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. +commaDelimited | `array` | `query`, `path` | Comma separated array values. This option replaces `collectionFormat` equal to `csv`. +spaceDelimited | `array` | `query`, `path` | Space separated array values. This option replaces `collectionFormat` equal to `ssv`. +pipeDelimited | `array` | `query`, `path` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes`. +deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. -Examples: -Assuming a parameter named `value` with one of the following values: +##### Style Examples + +Assuming a parameter named `color` with one of the following values: ``` - string -> "hello" + string -> "blue" array -> ["blue","black","brown"] - object -> { "x" : 100, "y" :200 } + object -> { "R" : 100, "G" :200, "B" : 150 } ``` The following table shows examples of how those values would be rendered. [`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` ----------- | ------ | -------- | -------- | --------|------- -matrix | false | ;value | ;value=hello | ;value=blue,black,brown | ;value=x,100,y200 -matrix | true | n/a | n/a | ;value=blue;value=black;value=brown | ;x=100;y=100 -label | false | . | .hello | .blue.black.brown | .x.100.y.200 -label | true | n/a | n/a | n/a | .x=100.y=200 -form | false | . | value=hello | value=blue,black,brown | value=x,100,y,200 -form | true | n/a | n/a | value=blue&value=black&value=brown | x=100&y=200 -space-delimited | false | n/a | n/a | blue%20black%20brown | x%20100%20y%20200 -pipe-delimited | false | n/a | n/a | blue\|black\|brown | x\|100\|y\|200 -deep-object | true | n/a | n/a | n/a | person[name]=Bob&person[lastname]=Brown +matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 +matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 +label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 +label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 +form | false | color= | color=blue | color=blue,black,brown | color=x,100,y,200 +form | true | color= | color=blue | color=blue&color=black&color=brown | x=100&y=200 +spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 +pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150 +deepObject | true | n/a | n/a | n/a | person[name]=Bob&person[lastname]=Brown This object can be extended with [Specification Extensions](#specificationExtensions). From 678e3a139a06a77ff60b6edae3c5886ea63b3469 Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 24 Jan 2017 13:45:59 -0500 Subject: [PATCH 06/10] Updates based on comments --- versions/3.0.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index cb9043b26e..415c58e29c 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -784,12 +784,12 @@ In order to support alternate ways of serializing parameters, a set of `style` v `style` | [`type`](#dataTypeType) | `in` | Comments ----------- | ------ | -------- | -------- -matrix | `string`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) -label | `string`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) -form | `string`, `array`, `object` | `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8) -commaDelimited | `array` | `query`, `path` | Comma separated array values. This option replaces `collectionFormat` equal to `csv`. -spaceDelimited | `array` | `query`, `path` | Space separated array values. This option replaces `collectionFormat` equal to `ssv`. -pipeDelimited | `array` | `query`, `path` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes`. +matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) +label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) +form | `primitive`, `array`, `object` | `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8) +commaDelimited | `array` | `query`, `path` | Comma seperated array values. This option replaces `collectionFormat` equal to `csv`. +spaceDelimited | `array` | `query`, `path` | Space seperated array values. This option replaces `collectionFormat` equal to `ssv`. +pipeDelimited | `array` | `query`, `path` | Pipe seperated array values. This option replaces `collectionFormat` equal to `pipes`. deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. @@ -798,23 +798,23 @@ deepObject | `object` | `query` | Provides a simple way of rendering nested obje Assuming a parameter named `color` with one of the following values: ``` - string -> "blue" + primitive -> "blue" array -> ["blue","black","brown"] object -> { "R" : 100, "G" :200, "B" : 150 } ``` The following table shows examples of how those values would be rendered. -[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` +[`style`](#dataTypeFormat) | `explode` | `empty` | `primitive` | `array` | `object` ----------- | ------ | -------- | -------- | --------|------- matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 -form | false | color= | color=blue | color=blue,black,brown | color=x,100,y,200 -form | true | color= | color=blue | color=blue&color=black&color=brown | x=100&y=200 +form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 +form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150 -deepObject | true | n/a | n/a | n/a | person[name]=Bob&person[lastname]=Brown +deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 This object can be extended with [Specification Extensions](#specificationExtensions). From 00160dec2de35905b1f99e7c40cc724c9da09b83 Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 24 Jan 2017 13:53:20 -0500 Subject: [PATCH 07/10] Fixed camelCase in examples --- 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 415c58e29c..59127fdece 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -835,7 +835,7 @@ A header parameter with an array of 64 bit integer numbers: "format": "int64" } }, - "style": "comma-delimited" + "style": "commaDelimited" } ``` @@ -849,7 +849,7 @@ schema: items: type: integer format: int64 -style: comma-delimited +style: commaDelimited ``` A path parameter of a string value: From dc7c002f69357a8edcac2e90d216e41f6e8f1324 Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 24 Jan 2017 14:00:38 -0500 Subject: [PATCH 08/10] changed primitive back to string in style example --- 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 59127fdece..ce2ea0268f 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -798,13 +798,13 @@ deepObject | `object` | `query` | Provides a simple way of rendering nested obje Assuming a parameter named `color` with one of the following values: ``` - primitive -> "blue" + string -> "blue" array -> ["blue","black","brown"] object -> { "R" : 100, "G" :200, "B" : 150 } ``` The following table shows examples of how those values would be rendered. -[`style`](#dataTypeFormat) | `explode` | `empty` | `primitive` | `array` | `object` +[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` ----------- | ------ | -------- | -------- | --------|------- matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 From 788591a0ef57aab8d66292208e938ec8b385d80c Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 24 Jan 2017 14:32:47 -0500 Subject: [PATCH 09/10] Added commaDelimited example --- versions/3.0.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index ce2ea0268f..68008996d9 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -763,7 +763,7 @@ Field Name | Type | Description format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details. style | `string` | Describes how the parameter value will be serialized depending on the specified [`type`](#parameterType). 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`. -explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of parameters this property has no effect. +explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of parameters this property has no effect. The default value is false. allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`. items | [Items Object](#itemsObject) | **Required if [`type`](#parameterType) is "array".** Describes the type of items in the array. default | * | Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See http://json-schema.org/latest/json-schema-validation.html#anchor101. Unlike JSON Schema this value MUST conform to the defined [`type`](#parameterType) for this parameter. @@ -788,8 +788,8 @@ matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defin label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) form | `primitive`, `array`, `object` | `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8) commaDelimited | `array` | `query`, `path` | Comma seperated array values. This option replaces `collectionFormat` equal to `csv`. -spaceDelimited | `array` | `query`, `path` | Space seperated array values. This option replaces `collectionFormat` equal to `ssv`. -pipeDelimited | `array` | `query`, `path` | Pipe seperated array values. This option replaces `collectionFormat` equal to `pipes`. +spaceDelimited | `array` | `query` | Space seperated array values. This option replaces `collectionFormat` equal to `ssv`. +pipeDelimited | `array` | `query` | Pipe seperated array values. This option replaces `collectionFormat` equal to `pipes`. deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. @@ -812,6 +812,7 @@ label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 +commaDelimited | false | n/a | n/a | blue,black,brown | R,100,G,200,B,150 spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150 deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 From 27df922fd635def7983940e5f659efc080fec38d Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 27 Jan 2017 15:43:35 -0500 Subject: [PATCH 10/10] Updated parameter to have schema as a child property --- versions/3.0.md | 38 +++++++++++--------------------------- 1 file changed, 11 insertions(+), 27 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 68008996d9..1e9a4f99ef 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -737,8 +737,6 @@ There are four possible parameter types. * Header - Custom headers that are expected as part of the request. * Cookie - Used to pass a specific cookie value to the API. -For complex parameter schemas, a serialization strategy is required. -For all types, a serialization strategy must be declared. ##### Fixed Fields Field Name | Type | Description @@ -748,39 +746,25 @@ 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 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`. 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 you to send a parameter with a name only or an empty value. Default value is `false`. -The content of the parameter is specified in one of two ways. By passing a schema and content-type, complex parameters may be serialized and passed: +The rules for serialization of the parameter are specified in one of two ways. +For simpler scenarios, a `Style` and `Schema` can be used to describe the structure and syntax of the parameter. Field Name | Type | Description ---|:---:|--- -content | [Content Object](#contentObject) | The content of the request body. +style | `string` | Describes how the parameter value will be serialized depending on type of the parameter value. +explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of parameters this property has no effect. 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) | The schema defining the type used for the parameter. -By defining a subset of JSON-schema properties: +For more complex scenarios a `content` object can be used to define the media-type and schema of the parameter. Field Name | Type | Description ---|:---:|--- -type | `string` | **Required.** The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"` or `"object"`. -format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details. -style | `string` | Describes how the parameter value will be serialized depending on the specified [`type`](#parameterType). -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`. -explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of parameters this property has no effect. The default value is false. -allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`. -items | [Items Object](#itemsObject) | **Required if [`type`](#parameterType) is "array".** Describes the type of items in the array. -default | * | Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See http://json-schema.org/latest/json-schema-validation.html#anchor101. Unlike JSON Schema this value MUST conform to the defined [`type`](#parameterType) for this parameter. -maximum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor17. -exclusiveMaximum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor17. -minimum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor21. -exclusiveMinimum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor21. -maxLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor26. -minLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor29. -pattern | `string` | See http://json-schema.org/latest/json-schema-validation.html#anchor33. -maxItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor42. -minItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor45. -uniqueItems | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor49. -enum | [*] | See http://json-schema.org/latest/json-schema-validation.html#anchor76. -multipleOf | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor14. - -In order to support alternate ways of serializing parameters, a set of `style` values are defined. +content | [Content Object](#contentObject) | The content of the request body. + +In order to support common ways of serializing simple parameters, a set of `style` values are defined. `style` | [`type`](#dataTypeType) | `in` | Comments ----------- | ------ | -------- | --------