2

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?

1 Answer 1

2

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:

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:

build output

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.

1
  • Thank you for your answer. Of course i already know and also used this form of documentation in C#. I was hoping that there might be something more specific. Probably, I will try AsyncAPI and use this approach as a fallback. Commented Nov 4, 2020 at 7:42

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.