Saunter 0.5.0

Saunter

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.0.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:

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.ChannelItemFilters.Add(new MyChannelItemFilter()); // Dynamically update ChanelItems
    options.OperationFilters.Add(new 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
}

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:

• AMQP
• HTTP
• Kafka
• MQTT

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

• This project is heavily inspired by Swashbuckle.
• We use NJsonSchema for the JSON schema heavy lifting,
• and Namotion.Reflection for pulling XML documentation.