diff --git a/versions/3.0.md b/versions/3.0.md index a0c0ee772e..b661c6b579 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -453,6 +453,7 @@ Field Name | Type | Description parameters | [[Parameter Object](#parameterObject) | [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). requestBody | [[Request Body Object](#requestBodyObject) | [Reference Object](#referenceObject)] | The request body applicable for this operation. responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation. +callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation. 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. deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`. 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. @@ -1050,6 +1051,36 @@ Response with no return value: description: object created ``` +#### 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 +---|:---:|--- +Callback name | [Callback Operation Object](#operationObject) | [Operation Object](#operationObject) | An operation object used to define a callback payload structure +^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 +``` + + #### Headers Object Lists the headers that can be sent as part of a response.