Abstract
Microservices are a popular software architectural style that decomposes a large application into smaller services. These microservices integrate at runtime to deliver business value to the users. With an increasing number of microservices, software projects become more difficult to manage. Specifically, maintaining consistent and up-to-date documentation becomes a challenge that can significantly affect the integration efforts in such projects. In this article, we present MSAdoc, an open source tool that helps to prevent documentation from going out-of-date quickly. The tool (1) enables decentralized documentation close to the source code of each microservice and those who have to document it, (2) aggregates documentation centrally across individual microservices to make the documentation accessible in one place and generate higher-order documentation, while (3) supporting technological heterogeneity by relying on the technology-agnostic JSON format. Using a tool like MSAdoc that implements several best practices, practitioners can accommodate the decentralized nature of microservice-based projects and alleviate the problem of maintaining central documentation that quickly becomes outdated.
Reference
Schwarz, G.-D. & Riehle, D. (2025). Documenting Microservice Integration with MSAdoc. In Proceedings of the 16th International Conference on Internetware (Internetware ’25), pp. 589-592 (ACM Press).
Download
Available on the publisher’s website (or as local copy).
Leave a Reply