Documenting Jersey REST API

Documentation is error-prone. So the best documentation should be the code itself… or automatically generated from the code.

I haven’t found any open source project that can do this so I created one. As I’m currently learning Scala, I decided to write the code with Scala. You can find the code in Bitbucket: https://bitbucket.org/enefem/restdoc

It’s by no mean complete so feel free to fork and add functionalities or ask for improvements.

Screenshot

How To Use

To use the tools, you must define an init-parameter in the Jersey Container. The param-name should be packageName and the param-value should the complete package name where your REST resources are located. Example is as follow:

<servlet>
    <servlet-name>Jersey REST Service</servlet-name>
    <servlet-class>
         com.sun.jersey.spi.container.servlet.ServletContainer
    </servlet-class>
    <init-param>
         <param-name>
              com.sun.jersey.config.property.packages
         </param-name>
         <param-value>
              de.fraunhofer.iais.tat.targeting.resources
         </param-value>
		  </init-param>
    <init-param>
         <param-name>packageName</param-name>
         <param-value>
             de.fraunhofer.iais.tat.targeting.resources
         </param-value>
    </init-param>
</servlet>

If you are using Guice and jersey-guice (which I do), you can define init-parameter as follow:

serve("/*").with(GuiceContainer.class,
   ImmutableMap.of("packageName", "de.fraunhofer.iais.tat.resource"));

And that’s all! The rest documentation should be available on path /restDoc.