AMQP messaging: How to generate documentation for consumers?

Question

My application publishes various messages (e.g., telemetry, changed-events, ...) to a RabbitMQ message-broker. The users have no access to the source-code and therefore, will need a separate documentation with all available exchanges, messages and their JSON payload.

How can i create/generate a documentation with this information classes like the following:

public class SensorMessagePublisher
{
    public void PublishTemperatureChangedMessage(string sensorId, int temperature)
    {
        //serialize parameters to JSON
        //call RabbitMQ-Client to publish message
    }

    public void PublishSensorConfigurationChangedMessage(List<Sensor> sensors)
    {
        //serialize parameters to JSON
        //call RabbitMQ-Client to publish message
    }
}

I have already looked at AsyncAPI, but their tools (e.g., Saunter) generate documentation only at runtime. Are there alternatives that provide an equivalent or similar approach at build time? Are there already best practices for such a widely used approach/tool?

Answer 1

I would personally use documentation comments. It is a good place to start at the very least. This looks like it is C#, where they are defined using /// (however most languages have them).

For C# in specific, there is more information available in the documentation.

For example:

/// <summary>
/// A class to handle sensor message publishing.
/// </summary>
public class SensorMessagePublisher
{
    /// <summary>
    /// Serializes temperature data to JSON and publishes a message.
    /// </summary>
    /// <param name="sensorId">The sensor id.</param>
    /// <param name="temperature">The temperature.</param>
    public void PublishTemperatureChangedMessage(string sensorId, int temperature)
    {
        //serialize parameters to JSON
        //call RabbitMQ-Client to publish message
    }
}

Result:

If you look in the the build section of the project properties you could see an output section, this has an option to export the comments as xml. This is useful if you want to generate more resources form the comments.

In Visual Studio:

There are third party solutions to generate various outputs with this xml, however you can also work with it quite easily and it can be integrated in tool chains.

However, it does rely on keeping the comments up to date.