A good documentation is essential for your (public) api and makes it pleasant to use. But maintaining api documentation manually is hard, tedious and error prone. Documentation is less likely to be updated if it´s far away from code. So why not generating the documentation if the relevant information is already at your fingertips: in the code?
Evaluating some of the tools for a project I am working on I saw some drawbacks of the existing tools. Let´s have a look.
Supports many different languages and I like the swagger UI. Personally I think that swagger is a bit to complex. Suppose you would like to generate your rest api documentation for spring at build time with gradle. AFAIK you will need swagger-springmvc and swagger-gradle-plugin. Maybe. To be honest, I think this usecase isn´t supported yet. But if you want to generate your documentation for a non spring project at runtime, swagger may be appropriate for you.
springdoclet and restdoclet
Generates the doc at compile time which would be a better solution for me, but unfortunately it was a bit quite in those projects the last time. And finally restdoclet has no gradle integration, which is a key feature for me.
Nice layout, even example requests are supported. But unfortunately you have to use jsondoc specific annotations on top of your spring annotations.
To sum up: I just would like to have a simple plugin for gradle which produces a useable html documentation for my springmvc app at build time. No intermediate format, no runtime dependencies. Thats it.
So I wrote gradle-springdoc-plugin, maybe just another documentation generator. The project is quite young, so don´t expect too much yet.
- Completly written in groovy
- Produces html documentation with twitter bootstrap
- Utilize an anotation processor to get information about spring mvc annotations
- To be used as gradle plugin
- CI with TravisCI
Things I have learnt
- It takes fun!
- You can invoke the java compiler at runtime - I tested the processor though
- Proper groovy (not just java with a .groovy suffix) takes fun and feels a bit like ruby
- An annotation processor is good to get compile time information about annotations
- Awkward old java api´s could be a bit more pleasant with groovy
- It´s simple to publish a project to maven central (NOT!) - but that´s another blog post
Here is an example page.