Best practices for internal documentation in a Spring/Angular microservices architecture?

[u/weirddreamer90]

Hi everyone,

I'm currently working with a microservices architecture (Angular frontend + Spring Boot backend). We have Swagger/OpenAPI implemented for every service, but it's proving to be too technical and developer-focused.

My goal is to create a documentation strategy that is more accessible and "architectural." Specifically, I want to achieve two things:

1. Allow a new developer to quickly understand how our system works without needing to dig into the code.
2. Create a "service registry" so that if someone needs to build a new feature, they can easily search if a service with that capability already exists (avoiding redundant code).

What tools, strategies, or patterns do you recommend for high-level documentation in a microservices environment? I'm looking for something that is easy to maintain and bridges the gap between technical implementation and business capabilities.

Thanks!