Updated examples throughout spec
MODIFY
versions/3.0.md
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": [
- "<Users><User name='Bob'/><User name='Diane'/><User name='Mary'/><User name='Bill'/></Users>",
- "<Users/>"
- ]
+ "examples": {
+ "list": {
+ "summary": "List of names",
+ "value": "<Users><User name='Bob'/><User name='Diane'/><User name='Mary'/><User name='Bill'/></Users>"
+ },
+ "empty": {
+ "summary":"Empty",
+ "value": "<Users/>"
+ }
+ }
},
"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:
- -
+ list:
+ summary: List of Names
+ value:
- Bob
- Diane
- Mary
- Bill
- - {}
+ empty:
+ summary: Empty
+ value: {}
'application/xml':
examples:
- - "<Users><User name='Bob'/><User name='Diane'/><User name='Mary'/><User name='Bill'/></Users>"
- - "<Users/>"
+ list:
+ summary: List of names
+ value: "<Users><User name='Bob'/><User name='Diane'/><User name='Mary'/><User name='Bill'/></Users>"
+ empty:
+ summmary: Empty list
+ value: "<Users/>"
'text/plain':
examples:
- - "Bob,Diane,Mary,Bill"
- - ""
+ list:
+ summary: List of names
+ value: "Bob,Diane,Mary,Bill"
+ empty:
+ summary: Empty
+ value: ""
```
#### <a name="mediaTypeObject"></a>Media Type Object
@@ -1889,7 +1945,8 @@ schemas:
properties:
name:
type: string
- 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 `*`:
@@ -2781,14 +2838,22 @@ example:
"required": [
"name"
],
- "examples": [
- {
+ "examples": {
+ "cat": {
+ "summary": "Big cat example",
+ "value": {
"name": "Puma",
"id": 1
- }, {
+ }
+ },
+ "dog": {
+ "summary": "Family dog example",
+ "value": {
"name": "Ferguson",
"id": 2
- }]
+ }
+ }
+ }
}
```
@@ -2803,9 +2868,15 @@ properties:
required:
- name
examples:
- - name: Puma
+ cat:
+ summary: Big cat example
+ value:
+ name: Puma
id: 1
- - name: Ferguson
+ dog:
+ summary: Family Dog
+ value:
+ name: Ferguson
id: 2
```

Updated examples throughout spec