Updated examples throughout spec

Author: darrelmiller

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:
-      - 
-        - Bob
-        - Diane
-        - Mary
-        - Bill
-      - {}
+      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,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