Skip to content

Commit c094380

Browse files
darrelmillerdarrelmiller
committed
Updates based on review
1 parent 6bcbde9 commit c094380

File tree

1 file changed

+21
-50
lines changed

1 file changed

+21
-50
lines changed

‎versions/3.0.md

Lines changed: 21 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,6 @@ Additional utilities can also take advantage of the resulting files, such as tes
5353
- [Callback Object](#callbackObject)
5454
- [Headers Object](#headersObject)
5555
- [Example Object](#exampleObject)
56-
- [Described Example Object](#describedExampleObject)
5756
- [Links Object](#linksObject)
5857
- [Link Object](#linkObject)
5958
- [Link Parameters Object](#linkParametersObject)
@@ -408,7 +407,7 @@ Field Name | Type | Description
408407
<a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject).
409408
<a name="componentsResponses"></a> responses | Map[`string`, [Response Object](#responseObject)] | An object to hold reusable [Response Objects](#responseObject).
410409
<a name="componentsParameters"></a> parameters | Map[`string`, [Parameter Object](#parameterObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
411-
<a name="componentsExamples"></a> examples | Map[`string`, [Described Example Object](#describedExampleObject)] | An object to hold reusable [Described Example Objects](#describedExampleObject).
410+
<a name="componentsExamples"></a> examples | Map[`string`, [Example Object](#exampleObject)] | An object to hold reusable [Example Objects](#exampleObject).
412411
<a name="componentsRequestBodies"></a> requestBodies | Map[`string`, [Request Body Object](#requestBodyObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
413412
<a name="componentsHeaders"></a> headers | Map[`string`, [Header object](#headerObject)] | An object to hold reusable [Header objects](#headerObject).
414413
<a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
@@ -938,8 +937,8 @@ Field Name | Type | Description
938937
<a name="parameterExplode"></a>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`.
939938
<a name="parameterAllowReserved"></a>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`.
940939
<a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | The schema defining the type used for the parameter.
941-
<a name="parameterExample"></a>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.
942-
<a name="parameterExamples"></a>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.
940+
<a name="parameterExample"></a>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.
941+
<a name="parameterExamples"></a>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.
943942

944943
For more complex scenarios a [Content Object](#contentObject) can be used to define the media type
945944
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.
11311130
"examples": {
11321131
"user" : {
11331132
"summary": "User Example",
1134-
"valueUrl": "http://foo.bar/examples/user-example.json"
1133+
"externalValue": "http://foo.bar/examples/user-example.json"
11351134
}
11361135
}
11371136
},
@@ -1142,23 +1141,23 @@ A request body with a referenced model definition.
11421141
"examples": {
11431142
"user" : {
11441143
"summary": "User example in XML",
1145-
"valueUrl": "http://foo.bar/examples/user-example.xml"
1144+
"externalValue": "http://foo.bar/examples/user-example.xml"
11461145
}
11471146
}
11481147
},
11491148
"text/plain": {
11501149
"examples": {
11511150
"user" : {
11521151
"summary": "User example in Plain text",
1153-
"valueUrl": "http://foo.bar/examples/user-example.txt"
1152+
"externalValue": "http://foo.bar/examples/user-example.txt"
11541153
}
11551154
}
11561155
},
11571156
"*/*": {
11581157
"examples": {
11591158
"user" : {
11601159
"summary": "User example in other format",
1161-
"valueUrl": "http://foo.bar/examples/user-example.whatever"
1160+
"externalValue": "http://foo.bar/examples/user-example.whatever"
11621161
}
11631162
}
11641163
}
@@ -1175,24 +1174,24 @@ content:
11751174
examples:
11761175
user:
11771176
summary: User Example
1178-
valueUrl: 'http://foo.bar/examples/user-example.json'
1177+
externalValue: 'http://foo.bar/examples/user-example.json'
11791178
'application/xml':
11801179
schema:
11811180
$ref: '#/components/schemas/User'
11821181
examples:
11831182
user:
11841183
summary: User Example in XML
1185-
valueUrl: 'http://foo.bar/examples/user-example.xml'
1184+
externalValue: 'http://foo.bar/examples/user-example.xml'
11861185
'text/plain':
11871186
examples:
11881187
user:
11891188
summary: User example in text plain format
1190-
valueUrl: 'http://foo.bar/examples/user-example.txt'
1189+
externalValue: 'http://foo.bar/examples/user-example.txt'
11911190
'*/*':
11921191
examples:
11931192
user:
11941193
summary: User example in other format
1195-
valueUrl: 'http://foo.bar/examples/user-example.whatever'
1194+
externalValue: 'http://foo.bar/examples/user-example.whatever'
11961195
```
11971196

11981197
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
13241323
Field Name | Type | Description
13251324
---|:---:|---
13261325
<a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body.
1327-
<a name="mediaTypeExample"></a>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.
1328-
<a name="mediaTypeExamples"></a>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.
1326+
<a name="mediaTypeExample"></a>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.
1327+
<a name="mediaTypeExamples"></a>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.
13291328
<a name="mediaTypeEncoding"></a>encoding | [Encoding Object](#encodingObject) | Encoding of the media type. The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`.
13301329

13311330
This object can be extended with [Specification Extensions](#specificationExtensions).
@@ -1894,41 +1893,13 @@ X-Rate-Limit-Reset:
18941893

18951894
#### <a name="exampleObject"></a>Example Object
18961895

1897-
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.
1898-
1899-
##### Example Object Example
1900-
1901-
Example representation for application/json media type of a Pet data type:
1902-
1903-
```json
1904-
{
1905-
"name": "Puma",
1906-
"type": "Dog",
1907-
"color": "Black",
1908-
"gender": "Female",
1909-
"breed": "Mixed"
1910-
}
1911-
```
1912-
1913-
```yaml
1914-
1915-
name: Puma
1916-
type: Dog
1917-
color: Black
1918-
gender: Female
1919-
breed: Mixed
1920-
1921-
```
1922-
1923-
#### <a name="describedExampleObject"></a>Described Example Object
1924-
19251896
##### Fixed Fields
19261897
Field Name | Type | Description
19271898
---|:---:|---
1928-
<a name="describedExampleSummary"></a>summary | `string` | Short description for the example.
1929-
<a name="describedExampleDescription"></a>description | `string` | Long description for the example.
1930-
<a name="describedExampleValue"></a>value | [Example Object](#exampleObject) | Embedded literal example. The `value` field and `valueUrl` field are mutually exclusive.
1931-
<a name="describedExampleValueUrl"></a>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.
1899+
<a name="exampleSummary"></a>summary | `string` | Short description for the example.
1900+
<a name="exampleDescription"></a>description | `string` | Long description for the example.
1901+
<a name="exampleValue"></a>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.
1902+
<a name="exampleExternalValue"></a>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.
19321903

19331904
This object can be extended with [Specification Extensions](#specificationExtensions).
19341905

@@ -1937,7 +1908,7 @@ for the value that it is accompanying. Tooling implementations MAY choose to
19371908
validate compatibility automatically, and reject the example value(s) if they
19381909
are not compatible.
19391910

1940-
##### Described Example Object Example
1911+
##### Example Object Example
19411912

19421913
```yaml
19431914
# in a model
@@ -1966,12 +1937,12 @@ schemas:
19661937
examples:
19671938
xmlExample:
19681939
summary: This is an example in XML
1969-
valueUrl: 'http://example.org/examples/address-example.xml'
1940+
externalValue: 'http://example.org/examples/address-example.xml'
19701941
'text/plain':
19711942
examples:
19721943
textExample:
19731944
summary: This is a text example
1974-
valueUrl: 'http://foo.bar/examples/address-example.txt'
1945+
externalValue: 'http://foo.bar/examples/address-example.txt'
19751946

19761947

19771948
# in a parameter
@@ -2667,7 +2638,7 @@ Field Name | Type | Description
26672638
<a name="schemaWriteOnly"></a>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`.
26682639
<a name="schemaXml"></a>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.
26692640
<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema.
2670-
<a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema.
2641+
<a name="schemaExample"></a>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.
26712642
<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage.
26722643

26732644
This object can be extended with [Specification Extensions](#specificationExtensions).

0 commit comments

Comments
 (0)