Skip to content

Commit 8d3dc3f

Browse files
darrelmillerdarrelmiller
committed
First attempt at described example
1 parent d232e6d commit 8d3dc3f

File tree

1 file changed

+113
-80
lines changed

1 file changed

+113
-80
lines changed

‎versions/3.0.md

Lines changed: 113 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,12 @@ Additional utilities can also take advantage of the resulting files, such as tes
4949
- [Response Object](#responseObject)
5050
- [Headers Object](#headersObject)
5151
- [Example Object](#exampleObject)
52+
- [Described Example Object](#describedExampleObject)
5253
- [Links Object](#linksObject)
5354
- [Link Object](#linkObject)
5455
- [Link Parameters Object](#linkParametersObject)
5556
- [Header Object](#headerObject)
5657
- [Tag Object](#tagObject)
57-
- [Examples Object](#examplesObject)
5858
- [Reference Object](#referenceObject)
5959
- [Schema Object](#schemaObject)
6060
- [XML Object](#xmlObject)
@@ -402,7 +402,7 @@ Field Name | Type | Description
402402
<a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject).
403403
<a name="componentsResponses"></a> responses | Map[`string`, [Response Object](#responseObject)] | An object to hold reusable [Response Objects](#responseObject).
404404
<a name="componentsParameters"></a> parameters | Map[`string`, [Parameter Object](#parameterObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
405-
<a name="componentsExamples"></a> examples | Map[`string`, [Example Object](#exampleObject)] | An object to hold reusable [Example Objects](#exampleObject).
405+
<a name="componentsExamples"></a> examples | Map[`string`, [Described Example Object](#describedExampleObject)] | An object to hold reusable [Described Example Objects](#describedExampleObject).
406406
<a name="componentsRequestBodies"></a> requestBodies | Map[`string`, [Request Body Object](#requestBodyObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
407407
<a name="componentsHeaders"></a> headers | Map[`string`, [Header object](#headerObject)] | An object to hold reusable [Header objects](#headerObject).
408408
<a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
@@ -932,8 +932,8 @@ Field Name | Type | Description
932932
<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`.
933933
<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`.
934934
<a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The schema defining the type used for the parameter.
935-
<a name="parameterExamples"></a>examples | [[Example Object](#exampleObject) <span>&#124;</span> [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.
936-
<a name="parameterExample"></a>example | [Example Object](#exampleObject) <span>&#124;</span> [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.
935+
<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.
936+
<a name="parameterExamples"></a>examples | Map[ `string`, [Described Example Object](#describedExampleObject) <span>&#124;</span> [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.
937937

938938
For more complex scenarios a [Content Object](#contentObject) can be used to define the media type
939939
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
12581258
##### Fixed Fields
12591259
Field Name | Type | Description
12601260
---|:---:|---
1261-
<a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The schema defining the type used for the request body.
1262-
<a name="mediaTypeExamples"></a>examples | [[Example Object](#exampleObject) <span>&#124;</span> [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.
1263-
<a name="mediaTypeExample"></a>example | [Example Object](#exampleObject) <span>&#124;</span> [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.
1261+
<a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) <span>&#124;</span> [Reference Object](#referenceObject) | The schema defining the type used for the request body.
1262+
<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.
1263+
<a name="mediaTypeExamples"></a>examples | Map[ `string`, [Described Example Object](#describedExampleObject) <span>&#124;</span> [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.
12641264
<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`.
12651265

12661266
This object can be extended with [Specification Extensions](#specificationExtensions).
@@ -1273,14 +1273,23 @@ This object can be extended with [Specification Extensions](#specificationExtens
12731273
"schema": {
12741274
"$ref": "#/components/schemas/Pet"
12751275
},
1276-
"examples": [{
1277-
"name": "Fluffy",
1278-
"petType": "Cat"
1279-
},
1280-
{
1281-
"name": "Rover",
1282-
"petType": "Frog"
1283-
}]
1276+
"examples": {
1277+
"cat" : {
1278+
"summary": "An example of a cat",
1279+
"value":
1280+
{
1281+
"name": "Fluffy",
1282+
"petType": "Cat"
1283+
}
1284+
},
1285+
"frog": {
1286+
"summary": "An example of a frog with a dog's name",
1287+
"value" : {
1288+
"name": "Rover",
1289+
"petType": "Frog"
1290+
}
1291+
}
1292+
}
12841293
}
12851294
}
12861295
```
@@ -1290,11 +1299,18 @@ application/json:
12901299
schema:
12911300
$ref: "#/components/schemas/Pet"
12921301
examples:
1293-
# converted directly from YAML to JSON
1294-
- name: Fluffy
1295-
petType: Cat
1296-
- {"name": "Rover", "petType": "Frog"}
1297-
1302+
cat:
1303+
summary: An example of a cat
1304+
value:
1305+
name: Fluffy
1306+
petType: Cat
1307+
frog:
1308+
summary: An example of a frog with a dog's name
1309+
value:
1310+
name: Rover
1311+
petType: Frog
1312+
dog:
1313+
$ref: "#/components/examples/dog-example"
12981314
```
12991315

13001316
##### Considerations for file uploads
@@ -1813,7 +1829,7 @@ X-Rate-Limit-Reset:
18131829

18141830
#### <a name="exampleObject"></a>Example Object
18151831

1816-
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.
1832+
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.
18171833

18181834
##### Example Example
18191835

@@ -1839,6 +1855,82 @@ breed: Mixed
18391855
18401856
```
18411857

1858+
#### <a name="describedExampleObject"></a>Described Example Object
1859+
1860+
##### Fixed Fields
1861+
Field Name | Type | Description
1862+
---|:---:|---
1863+
<a name="describedExampleSummary"></a>summary | `string` | Short description for the example.
1864+
<a name="describedExampleDescription"></a>description | `string` | Long description for the example.
1865+
<a name="describedExampleValue"></a>value | [Example Object](#exampleObject) | Embedded literal example. The `value` field and `valueUrl` field are mutually exclusive.
1866+
<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.
1867+
1868+
This object can be extended with [Specification Extensions](#specificationExtensions).
1869+
1870+
In all cases, the example value is expected to be compatible with the type schema
1871+
for the value that it is accompanying. Tooling implementations MAY choose to
1872+
validate compatibility automatically, and reject the example value(s) if they
1873+
are not compatible.
1874+
1875+
##### Example Described Example
1876+
1877+
```yaml
1878+
# in a model
1879+
schemas:
1880+
properties:
1881+
name:
1882+
type: string
1883+
example:
1884+
$ref: http://example.org/petapi-examples/OpenApi.json#/components/examples/name-example
1885+
1886+
# in a request body, note the plural `examples` as the Content-Type is set to `*`:
1887+
requestBody:
1888+
content:
1889+
'application/json':
1890+
schema:
1891+
$ref: '#/components/schemas/Address'
1892+
examples:
1893+
foo:
1894+
summary: A foo example
1895+
value: {"foo": "bar"}
1896+
bar:
1897+
summary: A bar example
1898+
value: {"bar": "baz"}
1899+
'application/xml':
1900+
examples:
1901+
xmlExample:
1902+
summary: This is an example in XML
1903+
valueUrl: 'http://example.org/examples/address-example.xml'
1904+
'text/plain':
1905+
examples:
1906+
textExample:
1907+
summary: This is a text example
1908+
valueUrl: 'http://foo.bar/examples/address-example.txt'
1909+
1910+
# in a parameter
1911+
parameters:
1912+
- name: 'zipCode'
1913+
in: 'query'
1914+
schema:
1915+
type: 'string'
1916+
format: 'zip-code'
1917+
examples:
1918+
zip-example:
1919+
$ref: '#/components/examples/zip-example'
1920+
1921+
# in a response
1922+
responses:
1923+
200:
1924+
description: your car appointment has been booked
1925+
content:
1926+
application/json:
1927+
schema:
1928+
$ref: '#/components/schemas/SuccessResponse'
1929+
examples:
1930+
confirmation-success:
1931+
$ref: '#/components/examples/confirmation-success'
1932+
```
1933+
18421934
#### <a name="linksObject"></a>Links Object
18431935
The links object represents a set of possible design-time links for a response.
18441936
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
23442436
description: Pets operations
23452437
```
23462438

2347-
#### <a name="examplesObject"></a>Examples Object
2348-
2349-
Anywhere an `example` may be given, a JSON Reference MAY be used, with the
2350-
explicit restriction that examples having a JSON format with object named
2351-
`$ref` are not allowed. This does mean that `example`, structurally, can be
2352-
either a string primitive or an object, similar to `additionalProperties`.
2353-
2354-
In all cases, the payload is expected to be compatible with the type schema
2355-
for the value that it is accompanying. Tooling implementations MAY choose to
2356-
validate compatibility automatically, and reject the example value(s) if they
2357-
are not compatible.
2358-
2359-
```yaml
2360-
# in a model
2361-
schemas:
2362-
properties:
2363-
name:
2364-
type: string
2365-
example:
2366-
$ref: http://foo.bar#/examples/name-example
2367-
2368-
# in a request body, note the plural `examples` as the Content-Type is set to `*`:
2369-
requestBody:
2370-
content:
2371-
'application/json':
2372-
schema:
2373-
$ref: '#/components/schemas/Address'
2374-
examples:
2375-
- {"foo": "bar"}
2376-
- {"bar": "baz"}
2377-
'application/xml':
2378-
examples:
2379-
- $ref: 'http://foo.bar#/examples/address-example.xml'
2380-
'text/plain':
2381-
examples:
2382-
- $ref: 'http://foo.bar#/examples/address-example.txt'
2383-
2384-
# in a parameter
2385-
2386-
parameters:
2387-
- name: 'zipCode'
2388-
in: 'query'
2389-
schema:
2390-
type: 'string'
2391-
format: 'zip-code'
2392-
example:
2393-
$ref: 'http://foo.bar#/examples/zip-example'
2394-
# in a response, note the plural `examples`:
2395-
responses:
2396-
200:
2397-
description: your car appointment has been booked
2398-
content:
2399-
application/json:
2400-
schema:
2401-
$ref: '#/components/schemas/SuccessResponse'
2402-
example:
2403-
$ref: http://foo.bar#/examples/address-example.json
2404-
```
24052439

24062440
#### <a name="referenceObject"></a>Reference Object
24072441

@@ -2509,7 +2543,6 @@ Field Name | Type | Description
25092543
<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.
25102544
<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema.
25112545
<a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema.
2512-
<a name="schemaExamples"></a>examples | Any | An array of free-formed properties to include examples for this schema.
25132546
<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage.
25142547

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

0 commit comments

Comments
 (0)