Merge pull request #3862 from handrews/editorial-311

Minor webhooks/callbacks and schema `examples` improvements (3.1.1)

Author: ralfhandl

versions/3.1.1.md

@@ -2039,7 +2039,7 @@ $response.header.Location | https://example.org/subscription/1
 
 ##### Callback Object Examples
 
-The following example uses the user provided `queryUrl` query string parameter to define the callback URL.  This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook.
+The following example uses the user provided `queryUrl` query string parameter to define the callback URL.  This is similar to a [webhook](#oasWebhooks), but differs in that the callback only occurs because of the initial request that sent the `queryUrl`.
 
 ```yaml
 myCallback:
@@ -2701,10 +2701,12 @@ additionalProperties:
   "required": [
     "name"
   ],
-  "example": {
-    "name": "Puma",
-    "id": 1
-  }
+  "examples": [
+    {
+      "name": "Puma",
+      "id": 1
+    }
+  ]
 }
 ```
 
@@ -2718,8 +2720,8 @@ properties:
     type: string
 required:
 - name
-example:
-  name: Puma
+examples:
+- name: Puma
   id: 1
 ```