One of the greatest new features provided by OpenAPI 3.1 is the support of webhooks. Indeed, a OpenAPI 3.1 documentation may include
paths and / or
paths were required for previous version.
Every webhook has a required
keyName, and some operations. If we follow this example, provided for OpenAPI 3.1 by OpenAPI Initiative:
webhooks:# Each webhook needs a namenewPet:# This is a Path Item Object, the only difference is that the request is initiated by the API providerpost:description: A new pet arrived, let's come and discover it IRL.requestBody:description: Information about a new pet in the systemcontent:application/json:schema:$ref: "#/components/schemas/Pet"responses:"200":description: Return a 200 status to indicate that the data was received successfully
Here, there is a single webhook whom
newPet , and a
POST operation. If such a documentation was generated by Bump (see live documentation):
Webhook's name is deduced from the
Webhook's operation name is extracted from field
As for endpoints, webhook has body parameters, responses... and some
request payloadexamples are generated.
Furthermore, webhooks are fully compatible with UI customization How to group operations?
By adding some
tags to your webhooks, you can re-organize how webhooks are named, sorted, and how webhooks operations are sorted.