Bielu.AspNetCore.AsyncApi 1.0.0

About

Bielu.AspNetCore.AsyncApi is a NuGet package that provides built-in support for generating AsyncAPI documents from minimal or controller-based APIs in ASP.NET Core.

This project is based on and inspired by:

• Saunter - The original AsyncAPI documentation generator for .NET
• Microsoft.AspNetCore.OpenApi - Microsoft's OpenAPI implementation that inspired the API design
• ByteBard.AsyncAPI.NET - AsyncAPI schema and serialization

Key Features

• Serves the generated document at runtime from a parameterized endpoint (/asyncapi/{documentName}.json or .yaml)
• Emits AsyncAPI 2.6 or 3.1, selected per document
• Generates the document at build time, so it can be committed and diffed in CI
• Customizable via document, operation and schema transformers
• Protocol bindings (AMQP, HTTP, MQTT, Kafka, …), plus first-party SignalR, gRPC, SSE and WebRTC bindings
• Multiple AsyncAPI documents from a single application
• Descriptions from XML doc comments, and message examples
• Native AOT and trimming support via a source-generated metadata provider

How to Use

To start using Bielu.AspNetCore.AsyncApi in your ASP.NET Core application, follow these steps:

Installation

dotnet add package Bielu.AspNetCore.AsyncApi

Configuration

In your Program.cs file, register the services provided by this package in the DI container and map the provided AsyncAPI document endpoint in the application.

var builder = WebApplication.CreateBuilder();

// Registers the required services
builder.Services.AddAsyncApi(options =>
{
    options.AddServer("mosquitto", "test.mosquitto.org", "mqtt");
    options.WithDefaultContentType("application/json")
        .WithDescription("My API Description");
});

var app = builder.Build();

// Adds the /asyncapi/{documentName}.json endpoint to the application
app.MapAsyncApi();

app.Run();

Viewing the Documentation

The library serves a standard AsyncAPI document at /asyncapi/{documentName}.json, so you can render it with any AsyncAPI-compatible UI. We recommend Scalar, which renders AsyncAPI channels, operations, messages, and schemas alongside your OpenAPI references:

dotnet add package Scalar.AspNetCore

app.MapAsyncApi();

app.MapScalarApiReference(options =>
{
    options.AddAsyncApiDocument("v1", "My API", "/asyncapi/v1.json");
});

Note: Scalar's AsyncAPI support is still evolving; not every part of the specification is rendered yet.

Main Types

The main types provided by this library are:

• AsyncApiOptions: Options for configuring AsyncAPI document generation.
• IDocumentTransformer: Transformer that modifies the AsyncAPI document generated by the library.
• ISchemaTransformer: Transformer that modifies generated schemas.

Related Packages

• Bielu.AspNetCore.AsyncApi.Attributes — attributes for defining channels, operations and messages
• Bielu.AspNetCore.AsyncApi.Cli — dotnet asyncapi (generate, validate, diff, merge)
• Bielu.AspNetCore.AsyncApi.Templates — dotnet new project templates
• Bielu.AspNetCore.AsyncApi.Versioning — one document per API version
• Bielu.AspNetCore.AsyncApi.Overlay — apply OpenAPI Overlays in the generation pipeline
• Bielu.AspNetCore.AsyncApi.Merger — merge documents from several services
• Protocol bindings: SignalR, gRPC, SSE, WebRTC
• Interactive consoles: Scalar.SignalR, Scalar.Grpc

Feedback & Contributing

Bielu.AspNetCore.AsyncApi is released as open-source under the MIT license. Bug reports and contributions are welcome at the GitHub repository.