29 May 2014
For some time I have meant to fully document all the different APIs I’m involved in. It gives a more professional feel, it helps integrators and front-end developers and it actually makes it easier to spot inconsistencies in naming or configuration.
Most of our software is written in 100% Java 7 or 8. I was making an effort to find tools that could help me do this automatically, because nothing is worse than outdated and misleading documentation. And believe it or not, I do not like maintaining projects and code if I do not need to, so the hunt for a documentation tool started.
In short (mainly because I’m too lazy to write all my reasoning), I found the documentation tools to fall into on or more of the following three categories:
The produced documentation did not look very appealing
The lack of support for important parts of information (I want at least security roles, HTTP methods, URL, and optionally JavaDoc documentation or other information carved into the source code)
Too much hassle to setup or the tool trying to be an integral part of my software.
(Or last, not free/open source)
Now it sounds that I have (re-)invented the wheel and the best thing since sliced bread, and it may very well not be, however I believe this project fills a gap.