Bielu API Descriptions
Tools for describing, generating and validating API descriptions in ASP.NET Core, for request/response APIs and for
event-driven, workflow-based ones.
The flagship package, Bielu.AspNetCore.AsyncApi, generates
AsyncAPI documents from minimal or controller-based APIs, with the same developer experience
as Microsoft.AspNetCore.OpenApi. Around it, the repository
ships libraries and tools for Arazzo workflows,
Overlay transformations, an RFC 9727
API catalog and CloudEvents messages.
📖 Full documentation: https://apidescriptions.bielu.pl/
Supported specifications
| Specification | Versions | Generated by | Read / validated by |
|---|
| AsyncAPI | 3.1.0 (default), 2.6.0 | Bielu.AspNetCore.AsyncApi | Bielu.AspNetCore.AsyncApi.Cli, Bielu.AspNetCore.AsyncApi.Merger |
| Arazzo | 1.0.x, 1.1.x | Bielu.AspNetCore.Arazzo (1.1.0 by default) | Bielu.Arazzo.NET, Bielu.Arazzo.NET.Readers, Bielu.Arazzo.Cli |
| Overlay | 1.0.x, 1.1.x | not generated; applied by Bielu.Overlay.NET | Bielu.Overlay.NET, Bielu.Overlay.NET.Readers, Bielu.Overlay.Cli |
| API Catalog (RFC 9727) | RFC 9727, as an RFC 9264 Linkset | Bielu.AspNetCore.ApiCatalog | not read |
| CloudEvents | 1.0 (binary and structured mode) | Bielu.AspNetCore.AsyncApi.CloudEvents, as AsyncAPI message headers or payload | not read |
| Apache Avro | 1.9.0 declared (schemaFormat), configurable | Bielu.AspNetCore.AsyncApi.Avro, as AsyncAPI message payloads | not read |
| Protocol Buffers | proto2, proto3 (schemaFormat version 2 or 3); editions files keep their JSON Schema | Bielu.AspNetCore.AsyncApi.Protobuf, as .proto payload sources | not read |
| xRegistry | 1.0-rc4 (message and schema registries; read-only) | Bielu.AspNetCore.XRegistry, served from the AsyncAPI documents | not read |
| Model Context Protocol | as negotiated by the ModelContextProtocol C# SDK 2.3 | Bielu.AspNetCore.ApiDescriptions.Mcp (experimental), as tools and resources over the served documents | not read |
The runtime libraries target .NET 10. See Supported .NET versions
for the support matrix and the policy for adding and removing targets.
Quick start
1. Install
dotnet add package Bielu.AspNetCore.AsyncApi
dotnet add package Bielu.AspNetCore.AsyncApi.Attributes
# Optional: interactive documentation UI
dotnet add package Scalar.AspNetCore
Prefer a ready-made project? Install the templates and run dotnet new asyncapi-webapi
(see Templates):
dotnet new install Bielu.AspNetCore.AsyncApi.Templates
2. Register the services and map the document
using Bielu.AspNetCore.AsyncApi.Extensions;
using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAsyncApi(options =>
{
options.AddServer("mosquitto", "test.mosquitto.org", "mqtt");
options.WithInfo("Streetlights API", "1.0.0");
});
var app = builder.Build();
app.MapAsyncApi(); // GET /asyncapi/v1.json
app.MapScalarApiReference(options =>
{
options.AddAsyncApiDocument("v1", "Streetlights API", "/asyncapi/v1.json");
});
app.Run();
3. Describe channels and operations
using Bielu.AspNetCore.AsyncApi.Attributes;
[AsyncApi]
public class StreetlightMessageBus
{
[Channel("light/measured", Servers = new[] { "mosquitto" })]
[SendOperation(typeof(LightMeasuredEvent), "Light", Summary = "Publishes a light measurement.")]
public void PublishLightMeasurement(LightMeasuredEvent lightMeasuredEvent) { }
}
Run the app and open /asyncapi/v1.json for the document or /scalar for the UI. The
Getting Started guide walks through this in more detail.
Features
- ✅ Runtime and build-time generation: serve documents from the app, or write them on
dotnet build with
dotnet getdocument, alongside the app's OpenAPI and Arazzo documents
- ✅ Document, operation and schema transformers, plus XML documentation comments as descriptions
- ✅ Multiple documents per app, and API Versioning (
Asp.Versioning) integration for a document per API version
- ✅ Protocol bindings: AMQP, Anypoint MQ, Google Pub/Sub, HTTP, IBM MQ, JMS, Kafka, MQTT, MQTT 5, NATS, Pulsar, ROS 2,
SNS, Solace, SQS and WebSockets, plus SignalR, gRPC, SSE and WebRTC
- ✅ Interactive Scalar UI with live consoles: invoke SignalR hubs and gRPC methods from the docs, and publish to or
tail Kafka channels through an opt-in server-side bridge (MQTT and AMQP drivers planned)
- ✅ Wolverine integration that documents channels and operations from Wolverine's message routing
- ✅ CloudEvents 1.0 messages: binary-mode headers per protocol binding, or the structured envelope
- ✅ Avro payloads (
schemaFormat: application/vnd.apache.avro) converted from the generated JSON Schemas
- ✅ Overlays applied in the generation pipeline, so the served and build-time documents are already transformed
- ✅ API catalog (RFC 9727) at
/.well-known/api-catalog, listing every AsyncAPI, OpenAPI and Arazzo document the app serves
- ✅ CNCF xRegistry (read-only message and schema registry) served from the app's AsyncAPI documents
- ✅ MCP server (experimental) that lets AI agents find the app's operations and read their complete contracts (servers, security, bindings, messages and schemas) from its AsyncAPI, OpenAPI and Arazzo documents
- ✅ Arazzo workflows that reference the app's own AsyncAPI and OpenAPI documents, validated at startup
- ✅ Document merging for API gateways, in code or from the CLI
- ✅ CLI tools to generate, merge, validate and diff AsyncAPI documents, and to validate Arazzo and apply Overlay documents
- ✅ Roslyn analyzers for attribute usage and service registration order
- ✅ Native AOT through a source-generated metadata provider, verified in CI
- ✅
dotnet new templates for Web API, SignalR, gRPC, worker and multi-project solutions
Packages
AsyncAPI
Scalar consoles
Arazzo, Overlay and API catalog
Tooling
Bielu.Spec.Shared and Bielu.Cli.Shared hold internals shared by the packages above and are not meant to be referenced
directly.
Examples
The src/examples folder has runnable samples:
| Example | Shows |
|---|
StreetlightsAPI | Minimal single-service app; the best starting point |
SignalRChat | SignalR hub with the interactive Scalar console |
GrpcGreeter | gRPC service with the interactive gRPC-Web console |
aspire | .NET Aspire microservices behind a YARP gateway that merges their AsyncAPI documents |
OverlayDemo | Overlays applied to an AsyncAPI and an Arazzo document |
AotStreetlights | PublishAot with the source-generated metadata provider |
BuildTimeDocuments | OpenAPI, AsyncAPI and Arazzo documents written by dotnet getdocument |
cd src/examples/StreetlightsAPI
dotnet run
# AsyncAPI JSON: http://localhost:5000/asyncapi/v1.json
# Scalar UI: http://localhost:5000/scalar
Documentation
AsyncAPI
Arazzo, Overlay and API catalog
The changelog lists what changed in each release.
Building from source
The repository needs the .NET 10 SDK. The solution is src/Bielu.AspNetCore.AsyncApi.slnx.
dotnet build src/Bielu.AspNetCore.AsyncApi.slnx
dotnet test
See CONTRIBUTING.md before opening a pull request. Every pull request needs a
changeset.
License
Copyright (c) 2025 Arkadiusz Biel. Licensed under the MIT License.
