This is a Maven Plugin for Spring MVC projects to automatically generate XML-based documentation for the REST API outlined in the project's Controllers source files.

The Maven plugin runs during the "package" phase of your build/install process, and scans the compiled source files using Java Reflection. By default, the plugin will not run during your install/deploy process. Please consult the "How Do I Run The Plugin?" section below for more information.

This tool will allow you to generate an automatic fresh version of your API documentation every time you build. You can build your own interface to interpret the XML and JSON files generated by this plugin into HTML or some other human-readable format.

Install the plugin like any other Maven plugin, and then add the following to your pom.xml in the project you wish to document:

	<build>
	    <plugins>
	        <plugin>
	            <groupId>MavenReflectionPlugin</groupId>
	            <artifactId>MavenReflectionPlugin</artifactId>
	            <version>1.0-SNAPSHOT</version>
	            <executions>
	                <execution>
	                    <id>DocExecution</id>
	                    <phase>package</phase>
	                    <goals>
	                        <goal>generatedocs</goal>
	                    </goals>
	                    <configuration>
	                        <!-- Package to scan -->
	                        <packageName>your.package.name</packageName>
	                        <!-- Destination for Documentation -->
	                        <!-- XML will go in docDestination/xml, JSON will go in docDestination/json -->
	                        <docDestination>${basedir}/your/folder</docDestination>
	                        <!-- The root URL that prefixes your annotations, just the path and NOT the domain -->
	                        <!-- Example: "impl" not "http://www.secondmarket.com/impl" -->
	                        <rootURL>impl</rootURL>
	                    </configuration>
	                </execution>
	            </executions>
	        </plugin>
	    </plugins>
	</build>

Note: To be safe, always prefix docDestination with ${basedir} to avoid complications with project hierarchy. This only applies if you are trying to direct the output of the plugin to a location on your classpath rather than an absolute URI on your filesystem.

By default, the plugin is configured not to run. If you want to generate documentation, add the flag -Ddocs.generate=true when you install/deploy the Maven application containing the plugin.

This plugin generates three basic classes of output.

• The first type is a unique XML file for each method in a Controller class that has a @RequestMapping annotation. These files are named based on the HTTP verb (GET, PUT, POST, DELETE) assigned to the method and live in a folder denoting their full URL path. Example: the file describing the call GET http://www.yoursite.com/rootURL/users/1 will be saved at docDestination/xml/rootURL/users/1/GET.xml.
• The second type is a JSON file for each non-standard (does not live in package java.*) class that is assigned to a parameter or return type of one of the methods outlined in the XML files. This file will be located at docDestination/json/${classname}.json
• The third and final output is a file location at docDestination/xml/summary.xml which describes the entire hierarchy of the XML documents generated by the plugin as they are represented on your filesystem. This is the best way to get an overview of your REST API and useful for parsing in order to navigate the folder hierarchy generated. This does not describe the URL paths of your application but rather the filesystem paths to the XML files that contain the API information.

There are a few limitations to the REST Doc Generator

• It only works on one package at a time.
• All classes must contain the proper annotations. Controllers must be labeled @Controller, methods/routes to be documented must have the @RequestMapping annotation, and parameters must be annotated with either @PathVariable, @RequestBody, @RequestHeader, or @RequestParameter.
• Generic support in parameter and return types is fairly basic, users requiring advanced support for nested generic classes should consider an advanced annotation-based JSON-generator like Jackson

There are many uses for the output generated by this plugin. At SecondMarket, we built a single-page webapp that used the summary.xml file to generate a collapsible-list hierarchy of the entire REST API. Each element in the list was a link to an XSLT-formatted version of the XML file for its REST call. Inside that XML, the { "fullname" : "xxx", "generic" : "yyy"} declarations were used to provide links to the JSON files describing the non-obvious return and parameter types of the methods.

Yes, there are a few non-critical issues with this plugin:

• The folder specified in docDestination must exist before the plugin is run