Callback 对象

A map of possible out-of band callbacks related to the parent operation. 映射中的每个值都是一个描述一组可能会被 API 提供者发起的请求和相应的响应的 Path Item 对象。用以标识回调对象的键是一个表达式，表达式会在运行时被计算，得到的值作为回调操作的 URL。

模式字段

字段名模式	类型	描述
{expression}	Path Item 对象	一个用于定义回调请求和响应的 Path Item 对象。 A complete example is available.

这个对象可能会被规范扩展扩展。

Key Expression

用于标识 Path Item 对象 的键是一个 runtime expression，此表达式会在运行时的 HTTP 请求/响应上下文中被计算，计算结果用于表示回调请求的 URL。 一个简单的例子是 $request.body#/url。 However, using a runtime expression the complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer RFC6901 can reference.

比如有如下 HTTP 请求：

POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 187

{
  "failedUrl" : "http://clientdomain.com/failed",
  "successUrls" : [
    "http://clientdomain.com/fast",
    "http://clientdomain.com/medium",
    "http://clientdomain.com/slow"
  ]
}

201 Created
Location: http://example.org/subscription/1

下方示例展示了各种表达式是如何被计算，这里假设回调操作有一个名为 eventType 的路径参数和一个名为 queryUrl 的查询参数。

Expression	Value
$url	http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning
$method	POST
$request.path.eventType	myevent
$request.query.queryUrl	http://clientdomain.com/stillrunning
$request.header.content-Type	application/json
$request.body#/failedUrl	http://clientdomain.com/stillrunning
$request.body#/successUrls/2	http://clientdomain.com/medium
$response.header.Location	http://example.org/subscription/1

Callback 对象示例

如下示例展示了一个通过请求体内的 id 和 email 属性指定的 URL 的回调。

myWebhook:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: webhook successfully processed and no retries will be performed