plugin_asyncapi.md

AsyncAPI Specification Plugin for SlimMessageBus

Please read the Introduction before reading this provider documentation.

• Introduction
• Configuration
• Sample AsyncAPI document
• Documentation

Introduction

The SlimMessageBus.Host.AsyncApi introduces a document generator for Saunter, which enables to generate an AsyncAPI specification from SlimMessageBus.

Configuration

On the SMB setup, use the mbb.AddAsyncApiDocumentGenerator() to add the IDocumentGenerator for Saunter library:

services.AddSlimMessageBus(mbb =>
{
    // Register the IDocumentGenerator for Saunter library
    mbb.AddAsyncApiDocumentGenerator();
});

Then register the Saunter services (in that order):

// Add Saunter to the application services. 
builder.Services.AddAsyncApiSchemaGeneration(options =>
{
    options.AsyncApi = new AsyncApiDocument
    {
        Info = new Info("SlimMessageBus AsyncAPI Sample API", "1.0.0")
        {
            Description = "This is a sample of the SlimMessageBus AsyncAPI plugin",
            License = new License("Apache 2.0")
            {
                Url = "https://www.apache.org/licenses/LICENSE-2.0"
            }
        }
    };
});

Saunter also requires to add the following endpoints (consult the Saunter docs):

// Register AsyncAPI docs via Sauter
app.MapAsyncApiDocuments();
app.MapAsyncApiUi();

See the Sample.AsyncApi.Service for a complete setup.

Sample AsyncAPI document

When running the mentioned sample, the AsyncAPI document can be obtained via the following link: https://localhost:7252/asyncapi/asyncapi.json

The generated document for the sample is available here as well.

Documentation

The comment and remarks are being taken from the code (for the consumer method and message type):

/// <summary>
/// Event when a customer is created within the domain.
/// </summary>
/// <param name="Id"></param>
/// <param name="Firstname"></param>
/// <param name="Lastname"></param>
public record CustomerCreatedEvent(Guid Id, string Firstname, string Lastname) : CustomerEvent(Id);

public class CustomerCreatedEventConsumer : IConsumer<CustomerCreatedEvent>
{
    /// <summary>
    /// Upon the <see cref="CustomerCreatedEvent"/> will store it with the database.
    /// </summary>
    /// <param name="message"></param>
    /// <returns></returns>
    public Task OnHandle(CustomerCreatedEvent message) { }
}

Ensure that your project has the GenerateDocumentationFile enabled (more here):

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>