Merge pull request OAI#763 from OAI/feature/callbacks

Callback feature

Author: fehguy

versions/3.0.md

@@ -472,6 +472,7 @@ Field Name | Type | Description
 <a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [___location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters).
 <a name="operationRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The request body applicable for this operation. 
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
+<a name="operationCallbacks"></a>callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation.
 <a name="operationSchemes"></a>schemes | [`string`] | The transfer protocol for the operation. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. The value overrides the OpenAPI Object [`schemes`](#oasSchemes) definition. 
 <a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`.
 <a name="operationSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for this operation. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used.
@@ -1248,6 +1249,36 @@ Response with no return value:
 description: object created
 ```
 
+#### <a name="callbackObject"></a>Callback Object
+
+A container for possible out-of band callbacks from an operation. A callback may be returned from an operation, calling back to the path specified in the operation object.
+
+##### Patterned Fields
+Field Pattern | Type | Description
+---|:---:|---
+<a name="responseName"></a>Callback name | [Callback Operation Object](#operationObject) <span>&#124;</span> [Operation Object](#operationObject) | An operation object used to define a callback payload structure
+<a name="responsesExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
+
+
+##### Callback Object Example
+
+A callback to the URL specified by the `url` parameter in the request
+
+
+```yaml
+myWebhook:
+  '$request.url':
+    post:
+      body:
+        name: postResponse
+        schema:
+          $ref: '#/definitions/SomePayload'
+      responses:
+        200:
+          description: webhook successfully processed an no retries will be performed
+```
+
+
 #### <a name="headersObject"></a>Headers Object
 Lists the headers that can be sent as part of a response.