Callback/webhook schema generation

[Jusstas]

I want to document my callbacks/webhooks as shown in the Petstore example. I am using serializers to serialize data and post it to some external URLs. Is there any way I can generate some of the schema required to achieve this? I know I can use postprocessing hooks to insert webhook callback operation, but I do not know how to get the schema from the serializer to use in it or if it is some better approach to this.

[tfranzel]

I see. This is in fact a missing feature and has not come up that often before. I'll have a look on how to integrate this.

In the meantime, postprocessing hooks can be a bit complicated but everything you need is indeed there. You have access to
def custom_postprocessing_hook(result, generator, request, public) where the complete schema is in result and all parsed serializer components are in generator.registry._components.

[tfranzel]

callback interface proposal in PR #666

[tfranzel]

closed by #666

[Jusstas]

Thank you ❤️

[CodeWithOz]

@Jusstas how did you structure your code so that the webhooks got picked up and included in the generated yaml file? I can't figure out how to do it. ☹️

[tfranzel]

@CodeWithOz you might want to look at the tests that use that functionality. It is easier to understand by example than explanation:

https://github.com/tfranzel/drf-spectacular/blob/master/tests/test_callbacks.py

and resulting schema:

https://github.com/tfranzel/drf-spectacular/blob/master/tests/test_callbacks.yml

[CodeWithOz]

@tfranzel worked a treat! Amazing thank you!

[nitsujri]

@CodeWithOz how did you do the webhook part? I copied the test_callbacks.py + yml and it looks good for callbacks but did you get ti like the webhooks?

I was hoping for this and maybe I'm doing something wrong?

[CodeWithOz]

This is what I did and it worked. By the way I'm using readme.io to generate my API documentation so I can't comment on the tool you're using. @nitsujri

[tfranzel]

Looks like webhook and callback are not the same thing. webhook was added in OpenAPI 3.1 and is not available in 3.0.3 (which we produce). So we only have callback at the moment.

excerpt from the 3.1 spec:

The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the callbacks feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An example is available.`

Redoc reference:
https://redocly.com/docs/openapi-visual-reference/webhooks/
https://redocly.com/docs/openapi-visual-reference/callbacks/

[nitsujri]

@tfranzel thanks for the update! I thought I was going bonkers missing something, but this is much appreciated.

My current work around is to mimic Redoc's example:

SPECTACULAR_SETTINGS = {
  "EXTENSIONS_ROOT": {
     "x-webhooks": {...},
  }
}

# View.py
@extend_schema(tags=["webhook_payloads"], auth=[])
class WebhookPayloadView(viewsets.GenericViewSet):
    serializer_class = MyAwesomeWebhookSerializer

The empty view class to generate the serializer's reference, then manually get the ref for $ref. It's brittle, but it works great for now.