Programming

17027 readers

54 users here now

Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!

Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.

Hope you enjoy the instance!

Rules

Follow the programming.dev instance rules
Keep content related to programming in some way
If you're posting long videos try to add in some form of tldr for those who don't want to watch videos

Wormhole

Follow the wormhole through a path of communities [email protected]

founded 1 year ago

MODERATORS

snowe

Ategon

[email protected]

How do you holistically document microservices in a multi-repo setup? (self.programming)

submitted 4 months ago by onlinepersona to c/programming

18 comments fedilink hide all child comments

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.

Anti Commercial-AI license

you are viewing a single comment's thread
view the rest of the comments

[–] MagicShel 1 points 4 months ago* (last edited 4 months ago) (1 children)

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.

[–] onlinepersona 1 points 4 months ago (1 children)

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.

Anti Commercial-AI license

[–] MagicShel 2 points 4 months ago (1 children)

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.

[–] onlinepersona 1 points 4 months ago

I don't mind using multiple compatible technologies. OpenAPI for services and something else that consumes an OpenAPI JSON or even JSON Schema to connect the different projects together and provide an overview.

Anti Commercial-AI license