From 5edd89e437d838aac58400860483f266a569c428 Mon Sep 17 00:00:00 2001 From: Darrel Date: Wed, 22 Feb 2017 18:02:35 -0500 Subject: [PATCH 1/3] Fixes for Example object --- versions/3.0.md | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 520992c254..851b46cfdb 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -765,7 +765,7 @@ Field Name | Type | Description 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. 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) | The schema defining the type used for the parameter. -examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples Array must be in the correct format as specified parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. +examples | [[Example Object](#exampleObject)] | Examples of the content type. Each example in the Examples Array must be in the correct format as specified parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. example | [Example Object](#exampleObject) | Example of the content type. The example object _must_ be in the correct format as specified in the parameter encoding. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the example provided by the the schema. For more complex scenarios a `content` object can be used to define the media-type @@ -1646,21 +1646,15 @@ X-Rate-Limit-Reset: type: integer ``` -#### Examples Object +#### Example Object Allows sharing examples for operation requests and responses. -##### Patterned Fields -Field Pattern | Type | Description ----|:---:|--- -{[media type](#mediaTypes)} | Any | The name of the property MUST be one of the Operation `produces` values (either implicit or inherited). The value SHOULD be an example of what such a response would look like. - -##### Examples Array Example +##### Example Example Example representation for application/json media type of a Pet data type: ```json -[ { "name": "Puma", "type": "Dog", @@ -1668,16 +1662,16 @@ Example representation for application/json media type of a Pet data type: "gender": "Female", "breed": "Mixed" } -] ``` ```yaml -- - name: Puma - type: Dog - color: Black - gender: Female - breed: Mixed + +name: Puma +type: Dog +color: Black +gender: Female +breed: Mixed + ``` #### Links Object From d84d386b1b896ceeeb86f19f304add90ecb7a323 Mon Sep 17 00:00:00 2001 From: Darrel Date: Thu, 23 Feb 2017 13:38:25 -0500 Subject: [PATCH 2/3] Changed should to SHOULD --- 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 851b46cfdb..b6223ed3bd 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -765,8 +765,8 @@ Field Name | Type | Description 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. 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) | The schema defining the type used for the parameter. -examples | [[Example Object](#exampleObject)] | Examples of the content type. Each example in the Examples Array must be in the correct format as specified parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. -example | [Example Object](#exampleObject) | Example of the content type. The example object _must_ be in the correct format as specified in the parameter encoding. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the example provided by the the schema. +examples | [[Example Object](#exampleObject)] | Examples of the content type. Each example in the Examples Array SHOULD be in the correct format as specified parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. +example | [Example Object](#exampleObject) | Example of the content type. The example object SHOULD be in the correct format as specified in the parameter encoding. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the example provided by the the schema. For more complex scenarios a `content` object can be used to define the media-type and schema of the parameter. This option is mutually exclusive with the simple scenario @@ -1092,8 +1092,8 @@ Each content type object provides schema and examples for a the media type ident Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body. -examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples Array must be in the correct format as specified in the _content_ type. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. -example | [Example Object](#exampleObject) | Example of the content type. The example object _should_ be in the correct format as specified in the _content_ type. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the the example provided by the schema. +examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples Array SHOULD be in the correct format as specified in the _content_ type. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. +example | [Example Object](#exampleObject) | Example of the content type. The example object SHOULD be in the correct format as specified in the _content_ type. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the the example provided by the schema. ##### Patterned Fields Field Pattern | Type | Description From 3534328067b649d8f42f598d0844374bc7d569ba Mon Sep 17 00:00:00 2001 From: Darrel Date: Mon, 27 Feb 2017 11:57:45 -0500 Subject: [PATCH 3/3] Fixes based on review comments --- versions/3.0.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 3da0429101..17dc0b99d1 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -761,8 +761,8 @@ Field Name | Type | Description 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. 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) | The schema defining the type used for the parameter. -examples | [[Example Object](#exampleObject)] | Examples of the content type. Each example in the Examples array SHOULD be in the correct format as specified parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. -example | [Example Object](#exampleObject) | Example of the content type. The example object SHOULD be in the correct format as specified in the parameter encoding. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the example provided by the the schema. +examples | [[Example Object](#exampleObject)] | Examples of the content type. Each example in the Examples array SHOULD be in the correct format as specified 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 | [Example Object](#exampleObject) | Example of the content type. The example object SHOULD be in the correct format as specified in the parameter encoding. 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 the schema. For more complex scenarios a `content` object can be used to define the media-type and schema of the parameter. This option is mutually exclusive with the simple scenario @@ -1089,12 +1089,8 @@ Each content type object provides schema and examples for a the media type ident Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body. -<<<<<<< HEAD -examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples Array SHOULD be in the correct format as specified in the _content_ type. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. -======= -examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples Array must be in the correct format as specified in the _content_ type. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. ->>>>>>> refs/remotes/origin/OpenAPI.next -example | [Example Object](#exampleObject) | Example of the content type. The example object SHOULD be in the correct format as specified in the _content_ type. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the the example provided by the schema. +examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples array SHOULD be in the correct format as specified in the _content_ type. 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 | [Example Object](#exampleObject) | Example of the content type. The example object SHOULD be in the correct format as specified in the _content_ type. 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. ##### Patterned Fields Field Pattern | Type | Description @@ -1648,7 +1644,7 @@ X-Rate-Limit-Reset: #### Example Object -Allows sharing examples for operation requests and responses. +Allows sharing examples for operation requests and responses. This object can either be a freeform object, array or primitive value. To represent examples of media types that cannot naturally represented in the OpenAPI definition, a string value can be used to contain the example with escaping where necessary. ##### Example Example