Saunter 0.13.0

dotnet add package Saunter --version 0.13.0                
NuGet\Install-Package Saunter -Version 0.13.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Saunter" Version="0.13.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Saunter --version 0.13.0                
#r "nuget: Saunter, 0.13.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Saunter as a Cake Addin
#addin nuget:?package=Saunter&version=0.13.0

// Install Saunter as a Cake Tool
#tool nuget:?package=Saunter&version=0.13.0                

Saunter

CI NuGet Badge

Saunter is an AsyncAPI documentation generator for dotnet.

ℹ Note that pre version 1.0.0, the API is regarded as unstable and breaking changes may be introduced.

Getting Started

See examples/StreetlightsAPI.

  1. Install the Saunter package

    dotnet add package Saunter
    
  2. In the ConfigureServices method of Startup.cs, configure Saunter.

    // Add Saunter to the application services. 
    services.AddAsyncApiSchemaGeneration(options =>
    {
        // Specify example type(s) from assemblies to scan.
        options.AssemblyMarkerTypes = new[] {typeof(StreetlightMessageBus)};
    
        // Build as much (or as little) of the AsyncApi document as you like.
        // Saunter will generate Channels, Operations, Messages, etc, but you
        // may want to specify Info here.
        options.AsyncApi = new AsyncApiDocument
        {
            Info = new Info("Streetlights API", "1.0.0")
            {
                Description = "The Smartylighting Streetlights API allows you\nto remotely manage the city lights.",
                License = new License("Apache 2.0")
                {
                    Url = "https://www.apache.org/licenses/LICENSE-2.0"
                }
            },
            Servers =
            {
                { "mosquitto", new Server("test.mosquitto.org", "mqtt") }
            }
        };
    });
    
  3. Add attributes to your classes which publish or subscribe to messages.

    [AsyncApi] // Tells Saunter to scan this class.
    public class StreetlightMessageBus : IStreetlightMessageBus
    {
        [Channel("publish/light/measured")] // Creates a Channel
        [PublishOperation(typeof(LightMeasuredEvent), Summary = "Inform about environmental lighting conditions for a particular streetlight.")] // A simple Publish operation.
        public void PublishLightMeasuredEvent(Streetlight streetlight, int lumens) {}
    
  4. Add saunter middleware to host the AsyncApi json document. In the Configure method of Startup.cs:

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapAsyncApiDocuments();
        endpoints.MapAsyncApiUi();
    });
    
  5. Use the published AsyncApi document:

    // HTTP GET /asyncapi/asyncapi.json
    {
        // Properties from Startup.cs
        "asyncapi": "2.1.0",
        "info": {
            "title": "Streetlights API",
            "version": "1.0.0",
            "description": "The Smartylighting Streetlights API allows you\nto remotely manage the city lights.",
           // ...
        },
        // Properties generated from Attributes
        "channels": {
            "light/measured": {
            "publish": {
                "operationId": "PublishLightMeasuredEvent",
                "summary": "Inform about environmental lighting conditions for a particular streetlight.",
            //...
    }
    
  6. Use the published AsyncAPI UI:

    AsyncAPI UI

Configuration

See the options source code for detailed info.

Common options are below:

services.AddAsyncApiSchemaGeneration(options =>
{
    options.AssemblyMarkerTypes = new[] { typeof(Startup) };   // Tell Saunter where to scan for your classes.
    
    options.AddChannelItemFilter<MyChannelItemFilter>();       // Dynamically update ChanelItems
    options.AddOperationFilter<MyOperationFilter>();           // Dynamically update Operations
    
    options.Middleware.Route = "/asyncapi/asyncapi.json";      // AsyncAPI JSON document URL
    options.Middleware.UiBaseRoute = "/asyncapi/ui/";          // AsyncAPI UI URL
    options.Middleware.UiTitle = "My AsyncAPI Documentation";  // AsyncAPI UI page title
}

JSON Schema Settings

The JSON schema generation can be customized using the options.JsonSchemaGeneratorSettings. Saunter defaults to the popular camelCase naming strategy for both properties and types.

For example, setting to use PascalCase:

services.AddAsyncApiSchemaGeneration(options =>
{
    options.JsonSchemaGeneratorSettings.TypeNameGenerator = new DefaultTypeNameGenerator();

    // Note: need to assign a new JsonSerializerSettings, not just set the properties within it.
    options.JsonSchemaGeneratorSettings.SerializerSettings = new JsonSerializerSettings 
    {
        ContractResolver = new DefaultContractResolver(),
        Formatting = Formatting.Indented;
    };
}

You have access to the full range of both NJsonSchema and JSON.NET settings to configure the JSON schema generation, including custom ContractResolvers.

Bindings

Bindings are used to describe protocol specific information. These can be added to the AsyncAPI document and then applied to different components by setting the BindingsRef property in the relevant attributes [OperationAttribute], [MessageAttribute], [ChannelAttribute]

// Startup.cs
services.AddAsyncApiSchemaGeneration(options =>
{
    options.AsyncApi = new AsyncApiDocument
    {
        Components = 
        {
            ChannelBindings = 
            {
                ["my-amqp-binding"] = new ChannelBindings
                {
                    Amqp = new AmqpChannelBinding
                    {
                        Is = AmqpChannelBindingIs.RoutingKey,
                        Exchange = new AmqpChannelBindingExchange
                        {
                            Name = "example-exchange",
                            VirtualHost = "/development"
                        }
                    }
                }
            }
        }
    }
});
[Channel("light.measured", BindingsRef = "my-amqp-binding")] // Set the BindingsRef property
public void PublishLightMeasuredEvent(Streetlight streetlight, int lumens) {}

Available bindings:

Multiple AsyncAPI documents

You can generate multiple AsyncAPI documents by using the ConfigureNamedAsyncApi extension method.

// Startup.cs

// Add Saunter to the application services. 
services.AddAsyncApiSchemaGeneration(options =>
{
    // Specify example type(s) from assemblies to scan.
    options.AssemblyMarkerTypes = new[] {typeof(FooMessageBus)};
}

// Configure one or more named AsyncAPI documents
services.ConfigureNamedAsyncApi("Foo", asyncApi => 
{
    asyncApi.Info = new Info("Foo API", "1.0.0");
    // ...
});

services.ConfigureNamedAsyncApi("Bar", asyncApi => 
{
    asyncApi.Info = new Info("Bar API", "1.0.0");
    // ...
});

Classes need to be decorated with the AsyncApiAttribute specifying the name of the AsyncAPI document.

[AsyncApi("Foo")]
public class FooMessageBus 
{
    // Any channels defined in this class will be added to the "Foo" document
}


[AsyncApi("Bar")]
public class BarMessageBus 
{
    // Any channels defined in this class will be added to the "Bar" document
}

Each document can be accessed by specifying the name in the URL

// GET /asyncapi/foo/asyncapi.json
{
    "info": {
        "title": "Foo API"
    }
}

// GET /asyncapi/bar/asyncapi.json
{
    "info": {
        "title": "Bar API"
    }
}

Contributing

See our contributing guide.

Feel free to get involved in the project by opening issues, or submitting pull requests.

You can also find me on the AsyncAPI community slack.

Thanks

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on Saunter:

Package Downloads
EasyDesk.CleanArchitecture.Web

Utilities for the ASP.NET Core web layer of the clean architecture as seen by EasyDesk.

Ev.ServiceBus.AsyncApi

This package helps you generate an Async API Schema. Resources registered in Ev.ServiceBus will be automatically added to the schema.

SlimMessageBus.Host.AsyncApi

Extension for SlimMessageBus that adds AsyncAPI specification generator for the Saunter library

Butterfly.API

Package Description

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Saunter:

Repository Stars
zarusz/SlimMessageBus
Lightweight message bus interface for .NET (pub/sub and request-response) with transport plugins for popular message brokers.
Version Downloads Last updated
0.13.0 374,851 1/16/2024
0.12.0 490,538 6/15/2023
0.11.0 266,405 10/3/2022
0.10.0 10,290 8/22/2022
0.9.1 236,586 11/8/2021
0.9.0 25,466 10/17/2021
0.8.0 15,540 9/10/2021
0.7.1 35,886 8/4/2021
0.7.0 415 8/4/2021
0.6.0 1,681 8/3/2021
0.5.0 832 7/28/2021
0.4.0 8,034 7/27/2021
0.3.1 1,111 7/19/2021
0.3.0 6,584 7/19/2021
0.2.0 98,359 8/4/2020
0.1.0 701 7/2/2020
0.1.0-alpha-46 207 7/1/2020
0.1.0-alpha-44 953 5/4/2020
0.1.0-alpha-42 213 5/4/2020
0.1.0-alpha-41 233 4/9/2020
0.1.0-alpha-39 222 4/9/2020
0.1.0-alpha-37 235 3/20/2020
0.1.0-alpha-34 236 10/21/2019
0.1.0-alpha-32 212 10/21/2019
0.1.0-alpha-29 267 10/21/2019
0.1.0-alpha-25 223 10/7/2019