From 8d3dc3f6d391432ac05066cba55e5e1a7cbd9e60 Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 7 Apr 2017 11:49:34 -0700 Subject: [PATCH 1/5] First attempt at described example --- versions/3.0.md | 193 ++++++++++++++++++++++++++++-------------------- 1 file changed, 113 insertions(+), 80 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 66610d5c4f..1ec796a937 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -49,12 +49,12 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Response Object](#responseObject) - [Headers Object](#headersObject) - [Example Object](#exampleObject) + - [Described Example Object](#describedExampleObject) - [Links Object](#linksObject) - [Link Object](#linkObject) - [Link Parameters Object](#linkParametersObject) - [Header Object](#headerObject) - [Tag Object](#tagObject) - - [Examples Object](#examplesObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [XML Object](#xmlObject) @@ -402,7 +402,7 @@ Field Name | Type | Description schemas | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject). responses | Map[`string`, [Response Object](#responseObject)] | An object to hold reusable [Response Objects](#responseObject). parameters | Map[`string`, [Parameter Object](#parameterObject)] | An object to hold reusable [Parameter Objects](#parameterObject). - examples | Map[`string`, [Example Object](#exampleObject)] | An object to hold reusable [Example Objects](#exampleObject). + examples | Map[`string`, [Described Example Object](#describedExampleObject)] | An object to hold reusable [Described Example Objects](#describedExampleObject). requestBodies | Map[`string`, [Request Body Object](#requestBodyObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject). headers | Map[`string`, [Header object](#headerObject)] | An object to hold reusable [Header objects](#headerObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). @@ -932,8 +932,8 @@ 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. -examples | [[Example Object](#exampleObject) | [Reference Object](#referenceObject)] | 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) | [Reference Object](#referenceObject) | 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. +example | [Example Object](#exampleObject) | Example of the media 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 the example provided by the schema. +examples | Map[ `string`, [Described Example Object](#describedExampleObject) | [Reference Object](#referenceObject)] | Described Examples of the media type. Each described 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 a [Content Object](#contentObject) can be used to define the media type and schema of the parameter. This option is mutually exclusive with the simple scenario @@ -1258,9 +1258,9 @@ Each Media Type Object provides schema and examples for a the media type identif ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -schema | [Schema Object](#schemaObject) | [Reference Object](#referenceObject)] | The schema defining the type used for the request body. -examples | [[Example Object](#exampleObject) | [Reference Object](#referenceObject)] | Examples of the media type. Each example in the Examples array SHOULD be in the correct format as specified in the media 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) | [Reference Object](#referenceObject) | Example of the media type. The example object SHOULD be in the correct format as specified in the media 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. +schema | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | The schema defining the type used for the request body. +example | [Example Object](#exampleObject) | Example of the media type. The example object SHOULD be in the correct format as specified in the media 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. +examples | Map[ `string`, [Described Example Object](#describedExampleObject) | [Reference Object](#referenceObject)] | Described Examples of the media type. Each described example SHOULD contain a value in the correct format as specified in the media 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. encoding | [Encoding Object](#encodingObject) | Encoding of the media type. The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1273,14 +1273,23 @@ This object can be extended with [Specification Extensions](#specificationExtens "schema": { "$ref": "#/components/schemas/Pet" }, - "examples": [{ - "name": "Fluffy", - "petType": "Cat" - }, - { - "name": "Rover", - "petType": "Frog" - }] + "examples": { + "cat" : { + "summary": "An example of a cat", + "value": + { + "name": "Fluffy", + "petType": "Cat" + } + }, + "frog": { + "summary": "An example of a frog with a dog's name", + "value" : { + "name": "Rover", + "petType": "Frog" + } + } + } } } ``` @@ -1290,11 +1299,18 @@ application/json: schema: $ref: "#/components/schemas/Pet" examples: - # converted directly from YAML to JSON - - name: Fluffy - petType: Cat - - {"name": "Rover", "petType": "Frog"} - + cat: + summary: An example of a cat + value: + name: Fluffy + petType: Cat + frog: + summary: An example of a frog with a dog's name + value: + name: Rover + petType: Frog + dog: + $ref: "#/components/examples/dog-example" ``` ##### Considerations for file uploads @@ -1813,7 +1829,7 @@ X-Rate-Limit-Reset: #### Example Object -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. +Allows sharing examples for operation requests and responses. This literal value can either be any JSON or YAML 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 @@ -1839,6 +1855,82 @@ breed: Mixed ``` +#### Described Example Object + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +summary | `string` | Short description for the example. +description | `string` | Long description for the example. +value | [Example Object](#exampleObject) | Embedded literal example. The `value` field and `valueUrl` field are mutually exclusive. +valueUrl | `string` | A Url that points to the literal example. This provides the ability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `valueUrl` field are mutually exclusive. + +This object can be extended with [Specification Extensions](#specificationExtensions). + +In all cases, the example value is expected to be compatible with the type schema +for the value that it is accompanying. Tooling implementations MAY choose to +validate compatibility automatically, and reject the example value(s) if they +are not compatible. + +##### Example Described Example + +```yaml +# in a model +schemas: + properties: + name: + type: string + example: + $ref: http://example.org/petapi-examples/OpenApi.json#/components/examples/name-example + +# in a request body, note the plural `examples` as the Content-Type is set to `*`: + requestBody: + content: + 'application/json': + schema: + $ref: '#/components/schemas/Address' + examples: + foo: + summary: A foo example + value: {"foo": "bar"} + bar: + summary: A bar example + value: {"bar": "baz"} + 'application/xml': + examples: + xmlExample: + summary: This is an example in XML + valueUrl: 'http://example.org/examples/address-example.xml' + 'text/plain': + examples: + textExample: + summary: This is a text example + valueUrl: 'http://foo.bar/examples/address-example.txt' + +# in a parameter + parameters: + - name: 'zipCode' + in: 'query' + schema: + type: 'string' + format: 'zip-code' + examples: + zip-example: + $ref: '#/components/examples/zip-example' + +# in a response + responses: + 200: + description: your car appointment has been booked + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessResponse' + examples: + confirmation-success: + $ref: '#/components/examples/confirmation-success' +``` + #### Links Object The links object represents a set of possible design-time links for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. @@ -2344,64 +2436,6 @@ name: pet description: Pets operations ``` -#### Examples Object - -Anywhere an `example` may be given, a JSON Reference MAY be used, with the -explicit restriction that examples having a JSON format with object named -`$ref` are not allowed. This does mean that `example`, structurally, can be -either a string primitive or an object, similar to `additionalProperties`. - -In all cases, the payload is expected to be compatible with the type schema -for the value that it is accompanying. Tooling implementations MAY choose to -validate compatibility automatically, and reject the example value(s) if they -are not compatible. - -```yaml -# in a model -schemas: - properties: - name: - type: string - example: - $ref: http://foo.bar#/examples/name-example - -# in a request body, note the plural `examples` as the Content-Type is set to `*`: - requestBody: - content: - 'application/json': - schema: - $ref: '#/components/schemas/Address' - examples: - - {"foo": "bar"} - - {"bar": "baz"} - 'application/xml': - examples: - - $ref: 'http://foo.bar#/examples/address-example.xml' - 'text/plain': - examples: - - $ref: 'http://foo.bar#/examples/address-example.txt' - -# in a parameter - - parameters: - - name: 'zipCode' - in: 'query' - schema: - type: 'string' - format: 'zip-code' - example: - $ref: 'http://foo.bar#/examples/zip-example' -# in a response, note the plural `examples`: - responses: - 200: - description: your car appointment has been booked - content: - application/json: - schema: - $ref: '#/components/schemas/SuccessResponse' - example: - $ref: http://foo.bar#/examples/address-example.json -``` #### Reference Object @@ -2509,7 +2543,6 @@ Field Name | Type | Description xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. -examples | Any | An array of free-formed properties to include examples for this schema. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. This object can be extended with [Specification Extensions](#specificationExtensions). From 2a4cc4a1111bd10fb2188379ee9064879669cb31 Mon Sep 17 00:00:00 2001 From: Darrel Date: Sun, 9 Apr 2017 23:26:36 -0400 Subject: [PATCH 2/5] Fixed section names --- versions/3.0.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 1ec796a937..437ca07e69 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -674,7 +674,7 @@ This object can be extended with [Specification Extensions](#specificationExtens "200": { "description": "pet response", "content": { - "*": { + "*/*": { "schema": { "type": "array", "items": { @@ -721,7 +721,7 @@ get: '200': description: pet response content: - *: + '*/*' : schema: type: array items: @@ -1831,7 +1831,7 @@ X-Rate-Limit-Reset: Allows sharing examples for operation requests and responses. This literal value can either be any JSON or YAML 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 +##### Example Object Example Example representation for application/json media type of a Pet data type: @@ -1863,7 +1863,7 @@ Field Name | Type | Description summary | `string` | Short description for the example. description | `string` | Long description for the example. value | [Example Object](#exampleObject) | Embedded literal example. The `value` field and `valueUrl` field are mutually exclusive. -valueUrl | `string` | A Url that points to the literal example. This provides the ability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `valueUrl` field are mutually exclusive. +valueUrl | `string` | A URL that points to the literal example. This provides the ability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `valueUrl` field are mutually exclusive. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1872,7 +1872,7 @@ for the value that it is accompanying. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if they are not compatible. -##### Example Described Example +##### Described Example Object Example ```yaml # in a model @@ -1906,7 +1906,8 @@ schemas: textExample: summary: This is a text example valueUrl: 'http://foo.bar/examples/address-example.txt' - + + # in a parameter parameters: - name: 'zipCode' @@ -2436,7 +2437,6 @@ name: pet description: Pets operations ``` - #### Reference Object A simple object to allow referencing other components in the specification, internally and externally. From 6bcbde99c65a0ad23c2e426eba8eb736fe7921de Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 11 Apr 2017 11:12:37 -0400 Subject: [PATCH 3/5] Updated examples throughout spec --- versions/3.0.md | 163 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 117 insertions(+), 46 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 0c8fe07229..137b28186b 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1128,20 +1128,38 @@ A request body with a referenced model definition. "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/examples/user-example.json" ] + "examples": { + "user" : { + "summary": "User Example", + "valueUrl": "http://foo.bar/examples/user-example.json" + } + } }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/examples/user-example.xml" ] + "examples": { + "user" : { + "summary": "User example in XML", + "valueUrl": "http://foo.bar/examples/user-example.xml" + } + } }, "text/plain": { - "examples": [ "http://foo.bar/examples/user-example.txt" ] + "examples": { + "user" : { + "summary": "User example in Plain text", + "valueUrl": "http://foo.bar/examples/user-example.txt" + } + } }, "*/*": { - "example": { - "$ref": "http://foo.bar/examples/user-example.whatever" + "examples": { + "user" : { + "summary": "User example in other format", + "valueUrl": "http://foo.bar/examples/user-example.whatever" + } } } } @@ -1155,18 +1173,26 @@ content: schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/examples/user-example.json' + user: + summary: User Example + valueUrl: 'http://foo.bar/examples/user-example.json' 'application/xml': schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/examples/user-example.xml' + user: + summary: User Example in XML + valueUrl: 'http://foo.bar/examples/user-example.xml' 'text/plain': examples: - - 'http://foo.bar/examples/user-example.txt' + user: + summary: User example in text plain format + valueUrl: 'http://foo.bar/examples/user-example.txt' '*/*': - example: - $ref: 'http://foo.bar/examples/user-example.whatever' + examples: + user: + summary: User example in other format + valueUrl: 'http://foo.bar/examples/user-example.whatever' ``` A body parameter that is an array of string values: @@ -1216,22 +1242,40 @@ Each key in the Content Object is the media type of the [Media Type Object](#med "type": "string" } }, - "examples": [ - ["Bob","Diane","Mary","Bill"], - [] - ] + "examples": { + "list": { + "summary": "List of names", + "value" : ["Bob","Diane","Mary","Bill"] + }, + "empty":{ + "summary": "Empty List", + "value": [] + } + } }, "application/xml": { - "examples": [ - "", - "" - ] + "examples": { + "list": { + "summary": "List of names", + "value": "" + }, + "empty": { + "summary":"Empty", + "value": "" + } + } }, "text/plain": { - "examples": [ - "Bob,Diane,Mary,Bill", - "" - ] + "examples": { + "list": { + "summary": "List of names", + "value": "Bob,Diane,Mary,Bill" + }, + "empty": { + "summary": "Empty", + "value" : "" + } + } } } ``` @@ -1244,21 +1288,33 @@ content: items: type: string examples: - - - - Bob - - Diane - - Mary - - Bill - - {} + list: + summary: List of Names + value: + - Bob + - Diane + - Mary + - Bill + empty: + summary: Empty + value: {} 'application/xml': examples: - - "" - - "" + list: + summary: List of names + value: "" + empty: + summmary: Empty list + value: "" 'text/plain': examples: - - "Bob,Diane,Mary,Bill" - - "" + list: + summary: List of names + value: "Bob,Diane,Mary,Bill" + empty: + summary: Empty + value: "" ``` #### Media Type Object @@ -1889,8 +1945,9 @@ schemas: properties: name: type: string - example: - $ref: http://example.org/petapi-examples/OpenApi.json#/components/examples/name-example + examples: + name: + $ref: http://example.org/petapi-examples/OpenApi.json#/components/examples/name-example # in a request body, note the plural `examples` as the Content-Type is set to `*`: requestBody: @@ -2781,14 +2838,22 @@ example: "required": [ "name" ], - "examples": [ - { - "name": "Puma", - "id": 1 - }, { - "name": "Ferguson", - "id": 2 - }] + "examples": { + "cat": { + "summary": "Big cat example", + "value": { + "name": "Puma", + "id": 1 + } + }, + "dog": { + "summary": "Family dog example", + "value": { + "name": "Ferguson", + "id": 2 + } + } + } } ``` @@ -2803,10 +2868,16 @@ properties: required: - name examples: - - name: Puma - id: 1 - - name: Ferguson - id: 2 + cat: + summary: Big cat example + value: + name: Puma + id: 1 + dog: + summary: Family Dog + value: + name: Ferguson + id: 2 ``` ###### Models with Composition From c0943807468fd704ab4a1d2293e463c487fd776a Mon Sep 17 00:00:00 2001 From: Darrel Date: Sat, 15 Apr 2017 20:24:09 -0400 Subject: [PATCH 4/5] Updates based on review --- versions/3.0.md | 71 +++++++++++++++---------------------------------- 1 file changed, 21 insertions(+), 50 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 137b28186b..edcdd6f95b 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -53,7 +53,6 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Callback Object](#callbackObject) - [Headers Object](#headersObject) - [Example Object](#exampleObject) - - [Described Example Object](#describedExampleObject) - [Links Object](#linksObject) - [Link Object](#linkObject) - [Link Parameters Object](#linkParametersObject) @@ -408,7 +407,7 @@ Field Name | Type | Description schemas | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject). responses | Map[`string`, [Response Object](#responseObject)] | An object to hold reusable [Response Objects](#responseObject). parameters | Map[`string`, [Parameter Object](#parameterObject)] | An object to hold reusable [Parameter Objects](#parameterObject). - examples | Map[`string`, [Described Example Object](#describedExampleObject)] | An object to hold reusable [Described Example Objects](#describedExampleObject). + examples | Map[`string`, [Example Object](#exampleObject)] | An object to hold reusable [Example Objects](#exampleObject). requestBodies | Map[`string`, [Request Body Object](#requestBodyObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject). headers | Map[`string`, [Header object](#headerObject)] | An object to hold reusable [Header objects](#headerObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). @@ -938,8 +937,8 @@ 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 | [Example Object](#exampleObject) | Example of the media 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 the example provided by the schema. -examples | Map[ `string`, [Described Example Object](#describedExampleObject) \| [Reference Object](#referenceObject)] | Described Examples of the media type. Each described 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 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 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. +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 a [Content Object](#contentObject) can be used to define the media type and schema of the parameter. This option is mutually exclusive with the simple scenario @@ -1131,7 +1130,7 @@ A request body with a referenced model definition. "examples": { "user" : { "summary": "User Example", - "valueUrl": "http://foo.bar/examples/user-example.json" + "externalValue": "http://foo.bar/examples/user-example.json" } } }, @@ -1142,7 +1141,7 @@ A request body with a referenced model definition. "examples": { "user" : { "summary": "User example in XML", - "valueUrl": "http://foo.bar/examples/user-example.xml" + "externalValue": "http://foo.bar/examples/user-example.xml" } } }, @@ -1150,7 +1149,7 @@ A request body with a referenced model definition. "examples": { "user" : { "summary": "User example in Plain text", - "valueUrl": "http://foo.bar/examples/user-example.txt" + "externalValue": "http://foo.bar/examples/user-example.txt" } } }, @@ -1158,7 +1157,7 @@ A request body with a referenced model definition. "examples": { "user" : { "summary": "User example in other format", - "valueUrl": "http://foo.bar/examples/user-example.whatever" + "externalValue": "http://foo.bar/examples/user-example.whatever" } } } @@ -1175,24 +1174,24 @@ content: examples: user: summary: User Example - valueUrl: 'http://foo.bar/examples/user-example.json' + externalValue: 'http://foo.bar/examples/user-example.json' 'application/xml': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example in XML - valueUrl: 'http://foo.bar/examples/user-example.xml' + externalValue: 'http://foo.bar/examples/user-example.xml' 'text/plain': examples: user: summary: User example in text plain format - valueUrl: 'http://foo.bar/examples/user-example.txt' + externalValue: 'http://foo.bar/examples/user-example.txt' '*/*': examples: user: summary: User example in other format - valueUrl: 'http://foo.bar/examples/user-example.whatever' + externalValue: 'http://foo.bar/examples/user-example.whatever' ``` A body parameter that is an array of string values: @@ -1324,8 +1323,8 @@ Each Media Type Object provides schema and examples for a the media type identif Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body. -example | [Example Object](#exampleObject) | Example of the media type. The example object SHOULD be in the correct format as specified in the media 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. -examples | Map[ `string`, [Described Example Object](#describedExampleObject) \| [Reference Object](#referenceObject)] | Described Examples of the media type. Each described example SHOULD contain a value in the correct format as specified in the media 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 | Any | Example of the media type. The example object SHOULD be in the correct format as specified in the media 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. +examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example object SHOULD contain a value in the correct format as specified in the media 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. encoding | [Encoding Object](#encodingObject) | Encoding of the media type. The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1894,41 +1893,13 @@ X-Rate-Limit-Reset: #### Example Object -Allows sharing examples for operation requests and responses. This literal value can either be any JSON or YAML 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 Object Example - -Example representation for application/json media type of a Pet data type: - -```json - { - "name": "Puma", - "type": "Dog", - "color": "Black", - "gender": "Female", - "breed": "Mixed" - } -``` - -```yaml - -name: Puma -type: Dog -color: Black -gender: Female -breed: Mixed - -``` - -#### Described Example Object - ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -summary | `string` | Short description for the example. -description | `string` | Long description for the example. -value | [Example Object](#exampleObject) | Embedded literal example. The `value` field and `valueUrl` field are mutually exclusive. -valueUrl | `string` | A URL that points to the literal example. This provides the ability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `valueUrl` field are mutually exclusive. +summary | `string` | Short description for the example. +description | `string` | Long description for the example. +value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. 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. +externalValue | `string` | A URL that points to the literal example. This provides the ability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1937,7 +1908,7 @@ for the value that it is accompanying. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if they are not compatible. -##### Described Example Object Example +##### Example Object Example ```yaml # in a model @@ -1966,12 +1937,12 @@ schemas: examples: xmlExample: summary: This is an example in XML - valueUrl: 'http://example.org/examples/address-example.xml' + externalValue: 'http://example.org/examples/address-example.xml' 'text/plain': examples: textExample: summary: This is a text example - valueUrl: 'http://foo.bar/examples/address-example.txt' + externalValue: 'http://foo.bar/examples/address-example.txt' # in a parameter @@ -2667,7 +2638,7 @@ Field Name | Type | Description writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". This means that it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. -example | Any | A free-form property to include an example of an instance for this schema. +example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. This object can be extended with [Specification Extensions](#specificationExtensions). From 8b4437e4d0594e84f033658e111fa80a5a6e3b99 Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 21 Apr 2017 11:51:18 -0400 Subject: [PATCH 5/5] Updates based on PR Comments --- versions/3.0.md | 105 ++++++++++++++---------------------------------- 1 file changed, 30 insertions(+), 75 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index edcdd6f95b..c100e27b2b 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -937,7 +937,7 @@ 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 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 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 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. 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 a [Content Object](#contentObject) can be used to define the media type @@ -1324,7 +1324,7 @@ Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body. example | Any | Example of the media type. The example object SHOULD be in the correct format as specified in the media 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. -examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example object SHOULD contain a value in the correct format as specified in the media 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. +examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example object SHOULD match the media type and specified schema if present. 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. encoding | [Encoding Object](#encodingObject) | Encoding of the media type. The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1343,14 +1343,23 @@ This object can be extended with [Specification Extensions](#specificationExtens "value": { "name": "Fluffy", - "petType": "Cat" + "petType": "Cat", + "color": "White", + "gender": "male", + "breed": "Persian" } }, - "frog": { - "summary": "An example of a frog with a dog's name", + "dog": { + "summary": "An example of a dog with a cat's name", "value" : { - "name": "Rover", - "petType": "Frog" + "name": "Puma", + "petType": "Dog", + "color": "Black", + "gender": "Female", + "breed": "Mixed" + }, + "frog": { + "$ref": "#/components/examples/frog-example" } } } @@ -1368,13 +1377,19 @@ application/json: value: name: Fluffy petType: Cat - frog: - summary: An example of a frog with a dog's name - value: - name: Rover - petType: Frog + color: White + gender: male + breed: Persian dog: - $ref: "#/components/examples/dog-example" + summary: An example of a dog with a cat's name + value: + name: Puma + petType: Dog + color: Black + gender: Female + breed: Mixed + frog: + $ref: "#/components/examples/frog-example" ``` ##### Considerations for file uploads @@ -1918,9 +1933,9 @@ schemas: type: string examples: name: - $ref: http://example.org/petapi-examples/OpenApi.json#/components/examples/name-example + $ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example -# in a request body, note the plural `examples` as the Content-Type is set to `*`: +# in a request body: requestBody: content: 'application/json': @@ -2532,7 +2547,6 @@ schemas: $ref: http://foo.bar#/examples/address-example.json ``` ->>>>>>> refs/remotes/origin/OpenAPI.next #### Reference Object A simple object to allow referencing other components in the specification, internally and externally. @@ -2792,65 +2806,6 @@ example: id: 1 ``` -###### Model with Examples - -```json -{ - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - }, - "required": [ - "name" - ], - "examples": { - "cat": { - "summary": "Big cat example", - "value": { - "name": "Puma", - "id": 1 - } - }, - "dog": { - "summary": "Family dog example", - "value": { - "name": "Ferguson", - "id": 2 - } - } - } -} -``` - -```yaml -type: object -properties: - id: - type: integer - format: int64 - name: - type: string -required: -- name -examples: - cat: - summary: Big cat example - value: - name: Puma - id: 1 - dog: - summary: Family Dog - value: - name: Ferguson - id: 2 -``` - ###### Models with Composition ```json