Generic API documenter for web-services¶
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.
The strategy I have used is to create an independent model using an APT processor in the form of ethlo api-documenter. This outputs the model as a JSON file.