How should I describe a callback (WebHook) in a code-first API with NSwag?

Question

I have built a simple REST service with .NET 6.0 using controllers and actions. I've added NSwag.AspNetCore and I'm using it to create an OpenAPI 3 document using AddOpenApiDocument() and the usual UI with UseSwaggerUi3().

One of my REST actions takes a webhook (or callback URL) from the client and later does a POST to it with a simple JSON object with three fields.

I see that the OpenAPI specification describes almost exactly this situation under the title Callbacks. This is almost identical to my situation, but I'm using NSwag to generate my OpenAPI document, not hand-crafting it.

I want to be able to describe the callback function and the payload it should expect in my generated OpenAPI document, and ideally my client should be able to consume my generated OpenAPI document with the NSwag C# client generator such that it creates a controller and action to provide a skeleton implementation and model class(es).

I have no idea if this is even possible...

Answer 1

see this code : https://github.com/RicoSuter/NSwag/pull/2363/files

1. Copy the files : OpenApiCallbackAttribute.cs OperationCallbackProcessor.cs to your project.

2. See SwaggerCallbackController.cs for how to use.

3. Add the new 'OperationCallbackProcessor' Processor in the swagger config :

   app.UseSwaggerReDoc(controllerList, settings =>
    {
   
     settings.GeneratorSettings.OperationProcessors.Add(new NSwag.Generation.Processors.OperationCallbackProcessor());
    }