[OAS 3.1.0] Webhooks field in OpenAPI object

[Azquelt]

OpenAPI 3.1.0 (see #333) adds support for webhooks which the API provider can call, but which may be configured out of band (i.e. in some way other than calling an operation described in the OpenAPI document).

This is similar to the way an Operation can have a callbacks, which represent a call that may be made by the API provider, after a client has called that operation.

Reference: https://spec.openapis.org/oas/v3.1.0.html#openapi-object

Example:

openapi: 3.1.0
info:
  title: Webhook Example
  version: 1.0.0
# Since OAS 3.1.0 the paths element isn't necessary. Now a valid OpenAPI Document can describe only paths, webhooks, or even only reusable components
webhooks:
  # Each webhook needs a name
  newPet:
    # This is a Path Item Object, the only difference is that the request is initiated by the API provider
    post:
      requestBody:
        description: Information about a new pet in the system
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully

components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Work needed

• Add webhooks to the OpenAPI model interface Add Webhooks model APIs #612
• TCK tests Add Webhooks model APIs #612
  • Model reader
  • Static file

Possible extension:

• Add support for defining webhooks via annotation PathItem and PathItemOperation annotations #629
  • TCK tests