How to Document Microservices

~ chriseyre2000

Here is a great article on using dot to document microservices:

https://articles.microservices.com/an-alternative-way-of-visualizing-microservice-architecture-837cbee575c1

I have forked and extended the gist to:

digraph architecture {
rankdir=LR;
// Storage – #303F9F (dark blue)
node[fillcolor="#303F9F" style="filled" fontcolor="white"];
database[label="DB"];
cache[label="Redis"];
// Client-side Apps – #FFEB3B (yellow)
node[fillcolor="#FFEB3B" style="filled" fontcolor="black"];
front_end[label="Front-end App"];
extension[label="Browser Extension"];
// Microservices – #C8E6C9 (light green)
node[fillcolor="#C8E6C9" style="filled" fontcolor="black"];
photos_ms[label="Photos MS"];
chats_ms[label="Chats MS"];
friends_ms[label="Friends MS"];
// API Gateways – #FFCCBC (light orange)
node[fillcolor="#FFCCBC" style="filled" fontcolor="black"];
auth_api[label="Auth API"];
my_app_api[label="Main API"];
// 3rd-party APIs – #CFD8DC (light grey)
node[fillcolor="#CFD8DC" style="filled" fontcolor="black"];
facebook_api[label="Facebook API"];
// Rabbit MQ – #FF0000 (red)
node[fillcolor="#FF0000" style="filled" fontcolor="white"];
subgraph client_side_apps {
front_end -> {auth_api, my_app_api};
extension -> {auth_api, my_app_api};
{rank=same; front_end, extension, auth_api};
}
subgraph api_gateways {
my_app_api -> {photos_ms, chats_ms, friends_ms};
}
subgraph microservices {
photos_ms -> {database};
chats_ms -> {database, cache};
friends_ms -> {database, facebook_api};
}
}
view raw visualize-ms-arch-step-2.dot hosted with ❤ by GitHub

This is all you need to generate the below image from the above text:

dot architecture.dot -Tpng > architecture.png

You can even add annotations to the lines by adding [label=”My Link”] to the connection before.

These are ideal to add to the README.md of github projects.

I especially like the idea of having a diagram with the source to create it under source control.

This requires you to install graphviz which can be done:

# Mac
brew install graphviz

# Windows
choco install graphviz

# Linux
sudo apt-get install graphviz

For the purists who want to keep their machines clean:

# Docker
cat file.dot | docker container run --rm -i vladgolubev/dot2png > file.png
Unknown's avatar

Published by chriseyre2000

Leave a comment