Let’s say I had a few microservices in different repositories and they communicated over HTTP using JSON. Some services are triggered directly by other microservices, but others can be triggered by events like a timer going off, a file being dropped into a bucket, a firewall rule blocking X amount of packets and hitting a threshold, etc.
Is there a way to document the microservices together in one holistic view? Maybe, how do you visualise the data, its schema (fields, types, …), and its flow between the microservices?
Bonus (optional) question: Is there a way to handle schema updates? For example generate code from the documentation that triggers a CI build in affected repos to ensure it still works with the updates.
Diagrams. Loads and loads of diagrams. One for each use-case.
Then I’d have one diagram to draw out dependencies between each service at the broadest level. Although depending on how messy your architecture is it can be very difficult to read, in my experience.
You do this all manually?
More or less. Either Excalidraw for your quick and dirty diagrams or I’ve used PlantUML + C4 Plug-in for your larger, more long lived diagrams with some success.
OpenAPI will let you generate both controller and swagger documentation from a single yaml configuration. That’s probably not the whole answer, but it’s the hard part. Then you just need something to index all the swagger docs.
This presumes Java. I don’t know about other ecosystems.
OpenAPI unfortunately doesn’t provide an overview of the different microservices. For example I won’t see that
$ServiceConsumer
is a consumer of messages from$ServiceProducer
. It only gets more complicated the more microservices are added.It could be part of the code generation solution, but I do wonder if OpenAPI is the only solution out there.
I would create a Jenkins task that runs during deployment that does whatever magical thing that updates your central index. That’s going to be implementation-dependent. I once worked on a custom workflow and documentation repository that did basically this, but I don’t have more info because I was only there a few weeks before getting moved to the contract I had actually been hired for. It would’ve been more complicated because they had api preview docs for things still under development.
Point is it was a custom solution and I’m not aware of an existing product.
Generate code from documentation
Let me stop you right there. If you want to generate API bindings, those should be generated from code, along with the documentation, not through it.
Generate API bindings from code? Then what’s the code for? Do you have an example?
OpenAPI can generate bindings from their spec, but the spec only seems to describe a single microservice.
I feel like this is just confusing specification with documentation.
Code generated from a specification, and documented. Swagger using the same specification could maybe sort of be documentation
For a while Peertube solely used OpenAPI to document the project. That’s spec, documentation, and code generation in one. Dunno when they switched to a separate documentation tech + OpenAPI, but it’s there.
We’re using backstage in combination with openapi. The schema is documented in OpenAPI, but how services are connected is done via backstage, which crawls all repositories and puts it together to form nice graphs we can traverse easily
That sounds great! I’ll look into backstage. It’s backstage.io?