Document REST service with Mermaid

For documentation of a REST service you can use a Javascript library called Mermaid ( From the GitHub page, Mermaid is recommended as follows:

Ever wanted to simplify documentation and avoid heavy tools like Visio when explaining your code? This is why mermaid was born, a simple markdown-like script language for generating charts from text via javascript.

Essentially you create a set of markdown (md) files that you include in a web page. First of all a webpage Documentation.aspx is added to the root of the web project.

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Documentation.aspx.cs" Inherits="Unive.Integratie.RechtshulpService.Documentation" %>

<!DOCTYPE html>

<html xmlns="">
<head runat="server">
    <script src=""></script>
    <script src=""></script>
        var config = {
            sequence : {
                actorMargin: 150,
                width: 250,
                useMaxWidth: true
    <link href="Style/modest.css" rel="stylesheet" type="text/css"/>
    <asp:Literal ID="htmlBody" runat="server"/>

The first thing to note, is the reference to Javascript library mermaid.min.js. The mermaid.Initialize action is not so important. This is only used for layout purposes.

Mermaid uses in-line documentation to generate the documentation page. The in-line documentation statements are contained in the controller files. As an example we can look at the RechtshulpController which contains a method CreateOrder.

Note that we use a mermaid node to generate a visual sequence diagram.

The documentation also contains a link to the Swagger documentation. But how does this magic happen? In the starup.cs file we see the following line of code:

var markdown = MethodDocumentationCollector.CreateControllerMethodsMarkdownFile(GetXmlCommentsPath());

Class MethodDocumentationCollector is contained in class library project Unive.Infa.Documentation which is added to the service solution. Method CreateControllerMethodsMarkdownFile collects the comments from the controller code and adds a link to the Swagger page for each method. The Swagger information is collected via method CreateMethodMD:

var sb = new StringBuilder();
sb.AppendFormat("##### [{4} {1}.{2} ({0})](swagger/ui/index#!/{1}/{1}_{2}){3}",
                            methodInfo.Deprecated ? "DEPRECATED!" : "");

The next statement in startup.cs writes the collected documentation to markdown file

var targetPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, @"App_Data\Documentation\");
 File.WriteAllText(targetPath, markdown);

Directory App_Data\Documentation is important. Apart from the service operation documentation, we also see general documentation before and after the documentation of the service operations. Know that all markdownfiles in App_Data\Documentation are read ordered by file name. Since the method documentation is contained in, we can add md files starting with a number < 5 to add text before the method documentation and a number > 5 to add text after the method description. Example:

## Integratie.RechtshulpService
### Doel van deze service
De RechtshulpService is verantwoordelijk is voor het ontvangen van orders.

### Technische architectuur
De rechtshulpservice heeft als doel om alle relevante gegevens over een order beschikbaar te maken naar andere systemen binnen [Bedrijf].

graph LR
	RechtshulpService --> OrderSystem

### Beveiliging
* De webservice is alleen benaderbaar via https.
* De webservice is alleen benaderbaar vanaf een geldig active directory account.
* De webservice ontsluit alleen (persoons)gegevens die inzichtelijk mogen zijn voor alle medewerkers.

Finally I want to point to a valuable link with the following address. In this link it’s explained how to create an md file via Visual Studio Code.

  • Download and install Visual Studio Code (, this is entirely different than the “normal” Visual Studio you use to write C# code).
  • In Visual Studio Code download and install the Mermaid Preview extension.
  • Restart Visual Studio Code when prompted.
  • Create a new markdown file named
  • Paste in the following diagram definition (including the lines that start with three backticks):
         Alice->>John: Hello John, how are you?
         John-->>Alice: Great!
  • Press to bring up the Visual Studio Code command window.
  • Type in > Preview Mermaid Diagram
  • Include the > character
  • You only need to type enough of the command that it shows up in the menu
  • You can type in various short cuts that will also bring up the command quickly
> Mermaid
> PMD (just the initials)
  • Click on any of the text in the left pane that is part of the diagram definition