Simplicity is the ultimate sophistication

Generic API documenter for web-services

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.

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.



blog comments powered by Disqus