Thilko Richter bio photo

Thilko Richter

I am a software craftsman with a passion for clean code and continuous learning.

Twitter LinkedIn XING Github Stackoverflow

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?

It´s nothing new and there are a couple of projects out there. Focussing on the java world you will find swagger, springdoclet, restdoclet, jsondoc and many more.

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.

Swagger

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.

Both projects using java doclets to gather compile time informations about annotations. Personally I think that an annotation processor is a better alternative.

jsondoc

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.

Used technologies

  • 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.