Saunter

Saunter automatically generates an AsyncAPI document based on your code. A key behavior to note is that schemas are automatically moved to the components/schemas section of the document to ensure valid AsyncAPI structure.

The document includes:

• channels: Defines the communication paths (e.g., publish/light/measured, subscribe/light/measured).
• components/schemas: Contains the data structures (e.g., lightMeasuredEvent).
• components/messages: Defines the messages used in channels, referencing the schemas.
• components/bindings: Contains channel and operation bindings (e.g., amqp or http bindings).

{
  "asyncapi": "2.6.0",
  "channels": {
    "publish/light/measured": {
      "message": { "$ref": "#/components/messages/lightMeasuredEvent" }
    }
  },
  "components": {
    "schemas": {
      "lightMeasuredEvent": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "format": "int32" },
          "lumens": { "type": "integer", "format": "int32" }
        }
      }
    }
  }
}

Bindings allow you to include protocol-specific details (like AMQP exchanges or HTTP methods) in your AsyncAPI document.

1. Define the bindings in the AsyncApiDocument.Components section within AddAsyncApiSchemaGeneration.
2. Reference these bindings in your attributes ([OperationAttribute], [MessageAttribute], or [ChannelAttribute]) using the BindingsRef property.

// 1. Define bindings in Startup.cs
services.AddAsyncApiSchemaGeneration(options =>
{
    options.AsyncApi = new AsyncApiDocument
    {
        Components = 
        {
            ChannelBindings =
            {
                ["amqpDev"] = new()
                {
                    new AMQPChannelBinding
                    {
                        Is = ChannelType.Queue,
                        Exchange = new()
                        {
                            Name = "example-exchange",
                            Vhost = "/development"
                        }
                    }
                }
            },
            OperationBindings =
            {
                {
                    "postBind",
                    new()
                    {
                        new HttpOperationBinding
                        {
                            Method = "POST",
                            Type = HttpOperationType.Response,
                        }
                    }
                }
            }
        }
    }
});

// 2. Reference bindings in attributes
[Channel("light.measured", BindingsRef = "amqpDev")]
public void PublishLightMeasuredEvent(Streetlight streetlight, int lumens) {}

[PublishOperation(typeof(LightMeasuredEvent), "Light", BindingsRef = "postBind")]
public void MeasureLight([FromBody] LightMeasuredEvent lightMeasuredEvent)

Register Saunter in your application services using AddAsyncApiSchemaGeneration. You must specify AssemblyMarkerTypes to tell Saunter which assemblies to scan for AsyncAPI attributes. You can also manually define parts of the AsyncApiDocument such as Info and Servers.

// 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.
    options.Middleware.UiTitle = "Streetlights API";
    options.AsyncApi = new AsyncApiDocument
    {
        Info = new AsyncApiInfo()
        {
            Title = "Streetlights API",
            Version = "1.0.0",
            Description = "The Smartylighting Streetlights API allows you to remotely manage the city lights.",
            License = new AsyncApiLicense()
            {
                Name = "Apache 2.0",
                Url = new("https://www.apache.org/licenses/LICENSE-2.0"),
            }
        },
        Servers =
        {
            ["mosquitto"] = new AsyncApiServer(){ Url = "test.mosquitto.org",  Protocol = "mqtt"},
            ["webapi"] = new AsyncApiServer(){ Url = "localhost:5000",  Protocol = "http"},
        },
    };
});

You can generate multiple distinct AsyncAPI documents by using ConfigureNamedAsyncApi.

1. In Startup.cs, use ConfigureNamedAsyncApi(name, callback) to define the configuration for each document.
2. Decorate your classes with [AsyncApi(name)] to specify which document they belong to.

Each document is accessible via a unique URL: /asyncapi/{name}/asyncapi.json.

// Startup.cs
services.AddAsyncApiSchemaGeneration(options =>
{
    options.AssemblyMarkerTypes = new[] {typeof(FooMessageBus)};
});

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
[AsyncApi("Foo")]
public class FooMessageBus 
{
    // Channels here go to "Foo" document
}

[AsyncApi("Bar")]
public class BarMessageBus 
{
    // Channels here go to "Bar" document
}

You can customize the behavior of the Saunter middleware using the AsyncApiOptions object in AddAsyncApiSchemaGeneration.

Common options include:

• AssemblyMarkerTypes: Types used to identify assemblies to scan.
• AddChannelFilter<T>: Adds a dynamic filter to update ChannelItems.
• AddOperationFilter<T>: Adds a dynamic filter to update Operations.
• Middleware.Route: The URL path for the AsyncAPI JSON document (default is /asyncapi/asyncapi.json).
• Middleware.UiBaseRoute: The URL path for the AsyncAPI UI (default is /asyncapi/ui/).
• Middleware.UiTitle: The title displayed on the AsyncAPI UI page.

services.AddAsyncApiSchemaGeneration(options =>
{
    options.AssemblyMarkerTypes = new[] { typeof(Startup) };   // Tell Saunter where to scan for your classes.
    
    options.AddChannelFilter<MyAsyncApiChannelFilter>();       // 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
}