From 5547736666d04d8e22010bdaae32c59a8e9a5a66 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 3 Sep 2020 18:51:36 +0200 Subject: [PATCH] Remove example and example --- versions/3.1.0.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 27921a9a75..e0cc84adac 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1029,11 +1029,11 @@ Field Name | Type | Description 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. example | Any | Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that 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 parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that 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 parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. If referencing a `schema` that contains an example, the `examples` value SHALL _override_ the example provided by the schema. 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. +When `examples` are provided in conjunction with the `schema` object, the examples MUST follow the prescribed serialization strategy for the parameter. Field Name | Type | Description @@ -1367,8 +1367,7 @@ Each Media Type Object provides schema and examples for the media type identifie Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) | The schema defining the content of the request, response, or parameter. -example | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` 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` field is mutually exclusive of the `example` field. 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. If referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1782,7 +1781,7 @@ Plain text response with headers: "text/plain": { "schema": { "type": "string", - "example": "whoa!" + "examples": ["whoa!"] } } }, @@ -1815,7 +1814,7 @@ content: text/plain: schema: type: string - example: 'whoa!' + examples: ['whoa!'] headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period @@ -1964,19 +1963,23 @@ requestBody: $ref: '#/components/schemas/Address' examples: foo: + # Example Object summary: A foo example value: {"foo": "bar"} bar: + # Example Object summary: A bar example value: {"bar": "baz"} 'application/xml': examples: xmlExample: + # Example Object summary: This is an example in XML externalValue: 'https://example.org/examples/address-example.xml' 'text/plain': examples: textExample: + # Example Object summary: This is a text example externalValue: 'https://foo.bar/examples/address-example.txt' ``` @@ -2313,7 +2316,6 @@ Field Name | Type | Description discriminator | [Discriminator Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](#schemaComposition) for more details. 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 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. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.

**Deprecated:** The `example` property has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2452,10 +2454,12 @@ additionalProperties: "required": [ "name" ], - "example": { - "name": "Puma", - "id": 1 - } + "examples": [ + { + "name": "Puma", + "id": 1 + } + ] } ``` @@ -2469,8 +2473,8 @@ properties: type: string required: - name -example: - name: Puma +examples: +- name: Puma id: 1 ```