At Qmino (the company that creates Miredot), we've written hundreds of REST APIs. We design and redesign until our APIs are an joy to use.
Documentation is the user interface of an API.
That is something we believe in firmly. The only way to really show off a good API is by providing beautiful and correct documentation for developers to enjoy.
That is why we are very meticulous on documentation. We even let the lack of Javadoc fail our builds and code reviews include checking the docs. Next to that, we make Miredot fail the build if it detects anything wrong with the REST API docs.
A few few years ago, we really couldn't find any good REST API documentation tool for Java. We wanted something that takes any existing artifacts such as Javadoc, the Java source code, annotations and so on. Something that understands the frameworks we use suchas jax-rs, spring and jackson, and turns it into something beautiful. Something that consumers of our APIs love to use.
That is exactly we are continuously aiming for with Miredot. And, so far, we're very proud of the result!