[scalesolved]

I've absolutely fallen in love with Spring Rest Docs https://projects.spring.io/spring-restdocs/ after a colleague introduced me to it.

Essentially you write tests that then generate your documentation, so you get a load of happy path integration tests and up to date documentation. It's a great way to ensure the documentation and code does what it says.

Our happy path integration tests produce markdown files detailing the route,payload, expected status codes etc and then we manually add these snippets to a menu markdown file. When we work on a feature branch with public API changes then our CI system detects documentation changes and when merged pushes to Jekyll.