[Question] How to host documentation in a central location?

[rsaltrelli]

My org makes heavy use of Swagger and Swashbuckle. Each of our APIs publishes its own documentation via a /swagger endpoint. We've talked about gathering all of that documentation and hosting it in a central location but haven't had a super compelling reason to do so.

Now that I'm looking at AsyncAPI and Saunter, we might have a good reason. A lot of our even-driven applications are pure stream processors. They don't have any HTTP endpoints so that's seemingly unnecessary functionality we'd have to build in just to access the AsyncAPI documentation. Also, if we were to do that, it seems like the visualization feature of AsyncAPI UI would be limited since it would only know about the inputs and outputs of this particular app. We wouldn't get the full topology of our event-driven architecture in one view.

So this brings me to my question. Is there a way to autogenerate AsyncAPI documentation using Saunter, extract it, and host it all in a central location?

[m-wild]

In theory you can use the IAsyncApiDocumentProvider.GetDocument() to retrieve the document without needing the http pipeline or middleware.

I guess the question is when/where would you do this... Perhaps as a step on app start-up, the app could generate the document and save it to a central location?

[m-wild]

We have started using this technique to host the list of channels/operations in a centralized API/database, using a background service which executes on app startup:

public class AsyncApiService : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;
    public AsyncApiService(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var scope = _serviceProvider.CreateScope();

        var asyncapi = scope.ServiceProvider.GetRequiredService<IAsyncApiDocumentProvider>();
        var opts = scope.ServiceProvider.GetRequiredService<IOptions<AsyncApiOptions>>();

        var doc = asyncapi.GetDocument(opts.Value, opts.Value.AsyncApi);

        var http = scope.ServiceProvider.GetRequiredService<IHttpClientFactory>().CreateClient();

        var res = await http.PostAsJsonAsync("<some-url-from-config>", doc);
        res.EnsureSuccessStatusCode();
    }
}