Close
HomeDev ToolsDocument REST service with Mermaid
Dev Tools / Services (WCF/REST)

Document REST service with Mermaid

admin 1429 views

For documentation of a REST service you can use a Javascript library called Mermaid (https://mermaidjs.github.io/). 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="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Documentation</title>
    <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.3.1.min.js"></script>
    <script src="https://unpkg.com/mermaid@8.0.0-rc.8/dist/mermaid.min.js"></script>
    <script>
        var config = {
            startOnLoad:true,
            sequence : {
                diagramMarginX:50,
                diagramMarginY:10,
                boxTextMargin:15,
                noteMargin:10,
                messageMargin:70,
                mirrorActors:true,
                actorMargin: 150,
                width: 250,
                useMaxWidth: true
            }
        };
        mermaid.initialize(config);
    </script>
    <link href="Style/modest.css" rel="stylesheet" type="text/css"/>
</head>
<body>
    <asp:Literal ID="htmlBody" runat="server"/>
</body>
</html>

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.Version,
                            methodInfo.Controller,
                            methodInfo.MethodName,
                            Environment.NewLine,
                            methodInfo.Deprecated ? "DEPRECATED!" : "");

The next statement in startup.cs writes the collected documentation to markdown file 5.Methods.md:

var targetPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, @"App_Data\Documentation\5.Methods.md");
 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 5.Methods.md, 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: 1.VoorDeMethodeBeschrijving.md

## 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].

```mermaid
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 (https://code.visualstudio.com/, 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 sequence.md
  • Paste in the following diagram definition (including the lines that start with three backticks): 
```mermaid
     sequenceDiagram
         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


You Might Also Like