How do you document your microservices?

Question

One thing that I always wondered about the many companies moving to microservices is how they keep track of all the services that are created and how they all relate. Is it a manual process or automated in some way? Or is it a "probably accurate" diagram that gets up dated when remembered about?

jka · Accepted Answer

An imaginary diagram of interactions between a large number of microservices isn't too different to a low-code representation of a software program.
The ways in which endpoints interact and receive webhooks are like function calls with arguments and callbacks.
Documentation for programs is tricky, but often it makes sense to embed the documentation alongside the code (docstrings, comments, etc).
And where possible, it's nice for programs to be self-explanatory (minimizing the amount of documentation required in the first place). That can often require careful choice (and rectification) of variable, function, file and directory names and structure.
I'm not sure if that'll help much in practice - perhaps it's an unrealistic comparison to make between microservice architectures and programs. But maybe it'll provide a few ideas.

thorin · Answer

We like to use swagger to document the endpoints / payloads etc for REST APIsFor other stuff we tend to just provide diagrams of servers/cloud services etc. Really the only way to understand it fully is to look at the code, but at least it's nice to have an entry point to the correct place. Unfortunately there are lots of non technical architects in my organization who tend to depend on documentation (which we have in confluence). It's not ideal really!