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
