[FR] Support for documenting webhooks

[sserrata]

Is your feature request related to a problem?

Currently, the plugin does not support documenting webhooks.

Describe the solution you'd like

Introduce webhook support, similar to how ReDoc currently handles them:

Describe alternatives you've considered

Not supporting them, since none of our current product APIs include them.

Additional context

OpenAPI 3.1 will make paths optional, which will be another way to imply/support webhook endpoints. To support them today (3.0) I believe we'd have to use vendor extensions:

x-webhooks:
  newPet:
    post:
      summary: New pet
      description: Information about a new pet in the systems
      operationId: newPet
      tags:
        - pet
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully

[koladev32]

Hi!

Interesting enhancement. Have you started working on it? I would love to contribute.

[pomSense]

+1 for this. Do you know if there a workaround for this in the meantime?

[sserrata]

Was able to put together a quick demo using the Petstore webhook example:

https://user-images.githubusercontent.com/9343811/208717991-ae9daff1-8873-4eda-a9f8-07777683f0ab.mov

I tried to mirror Redoc's implementation as closely as possible:

https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/PaloAltoNetworks/docusaurus-openapi-docs/main/demo/examples/petstore.yaml#tag/pet/operation/newPet

[sserrata]

Here's a link to a preview: https://docusaurus-openapi-36b86--pr370-m1d73twc.web.app/petstore/new-pet

Appreciate any feedback. It seems very similar to how we handle non-webhook operations but I'd like to make sure we aren't missing anything about webhooks.