diff --git a/examples/v3.0/callback-example.yaml b/examples/v3.0/callback-example.yaml new file mode 100644 index 0000000000..426ee39a76 --- /dev/null +++ b/examples/v3.0/callback-example.yaml @@ -0,0 +1,56 @@ +paths: + /streams: + post: + description: subscribes a client to receive out-of-band data + parameters: + - name: callbackUrl + in: query + required: true + description: | + the location where data will be sent. Must be network accessible + by the source server + schema: + type: string + format: uri + example: https://tonys-server.com + responses: + '201': + description: subscription successfully created + content: + application/json: + schema: + description: subscription information + required: + - subscriptionId + properties: + subscriptionId: + description: this unique identifier allows management of the subscription + type: string + example: 2531329f-fb09-4ef7-887e-84e648214436 + callbacks: + # the name `onData` is a convenience locator + onData: + # when data is sent, it will be sent to the `callbackUrl` provided + # when making the subscription PLUS the suffix `/data` + $request.query.callbackUrl/data: + post: + requestBody: + description: subscription payload + content: + application/json: + schema: + properties: + timestamp: + type: string + format: date-time + userData: + $ref: '#/components/schemas/UserLogData' + responses: + '202': + description: | + Your server implementation should return this HTTP status code + if the data was received successfully + '204': + description: | + Your server should return this HTTP status code if no longer interested + in further updates diff --git a/versions/3.0.md b/versions/3.0.md index d83f57acce..81e464930b 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1728,7 +1728,7 @@ The key value used to identify the callback object is an expression, evaluated a ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- -{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses. +{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses. A full example may be found at https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/examples/v3.0/callback-example.yaml This object can be extended with [Specification Extensions](#specificationExtensions).