JSONDoc

easily generate docs and playground for your RESTful API

Contacts

Email StackOverflow

How to: with Spring MVC

Declare the needed dependencies

If your web application already uses Spring MVC, then it's easy: the project jsondoc-springmvc already does it for you, so you need to include both jsondoc-core and jsondoc-springmvc dependencies.

<dependency>
        <groupId>org.jsondoc</groupId>
        <artifactId>jsondoc-springmvc</artifactId>
        <version>1.2.23</version>
</dependency>

Configure JSONDoc controller

The only thing to do on your side is to declare the jsondoc controller in your spring context.xml file:

<bean id="documentationController" class="org.jsondoc.springmvc.controller.JSONDocController">
	<constructor-arg name="version" value="1.0" />
	<constructor-arg name="basePath" value="http://localhost:8080/api" />
	<constructor-arg name="packages">
	  <list>
		<value>org.jsondoc.sample.controller</value> <!-- packages in which you have your spring controllers -->
		<value>org.jsondoc.sample.pojo</value> <!-- packages in which you have your objects -->
		<value>com.sample.external.pojo</value> <!-- they can also belong to external jars -->
	  </list>
	</constructor-arg>
	<property name="playgroundEnabled" value="true" /> <!-- optional -->
	<property name="displayMethodAs" value="URI" /> <!-- optional -->
</bean>

In this case the documentation will be generated at http://localhost:8080/api/jsondoc. You only have to specify the api version and the base path to give you readers a better information.

Change the base path of your web application, or better put a placeholder here and in the pom.xml and filter this file to have it replaced for free for different environments
In the packages list property you should put packages that contain spring controllers and objects needed for the documentation generation, as far as they are on the classpath. The scan is recursive.

See Configuration for more information about how to configure the JSONDoc controller.

Display the generated docs

With jsondoc-ui

You can include the jsondoc-ui project in your web application. This provides an interface to browse the generated documentation and a playground to test methods. It is built on Twitter Bootstrap and can be easily customized for you needs. To do this you need to get the jsondoc-ui jar, extract it and copy css, js, font, jsondoc-ui.html to your project's webapp folder. Check out the live demo here or the sample applications code. Here is the dependency to the jsondoc-ui:

<dependency>
        <groupId>org.jsondoc</groupId>
        <artifactId>jsondoc-ui</artifactId>
        <version>1.2.23</version>
</dependency>
Build your own viewer

If you are not satisfied with the standard interface, you can use the generated JSON documentation in a fully customized interface!

Version 1.2.23 | Licensed under MIT License

GitHub Project | Issues