rest-doclet

The purpose of this README file is to explain how one can easily generate Spring mvc based REST API documentation.

The rest-doclet enables automatic generation of documentation from REST service source code, and displays spring-annotated service operations, types and associated Javadoc. The detection of Spring artifacts is based on the presence of Spring annotations on Java classes and methods.

rest-doclet currently detects and documents the following types of Spring artifacts:

• Classes annotated with @Controller.
• Methods annotated with @RequestMapping.
• Parameters annotated with @PathVariable, @ RequestParam, @ RequestBody.

It also documents the following custom annotations:

• @JsonRequestExample
• @JsonResponseExample
• @PossibleResponseStatuses

These annotations are declared in the annotation-package.

Usage examples can be found at ServiceController.java.

Requirements

1. Download the rest-doclet project - https://github.com/CloudifySource/rest-doclet.git
2. Include the jdk lib/tools.jar on the classpath.

Rest-doclet generation process

Rest-doclet is generated when invoking the run method of the Generator.java class.

The run method operates in two main phases:

• Traverses all controller classes and generates a list of corresponding DocController classes, which contain all the data required for generating the documentation.
• Uses a velocity template to generate an html file that contains the final documentation.

Generating the documentation

The documentation can be generated by:

1. Invoking RestDoclet.start() or Generator.main() (both invoke Generator.run())

   Some constants in RestDocConstants.java class must be changed:

• RestDocConstants.SOURCE_PATH, RestDocConstants.CONTROLLERS_PACKAGE - specify the sources (where controller classes can be found)
• RestDocConstants.VELOCITY_TEMPLATE_PATH - specifies the template path, must be updated if a vm file other than the current (restDocletVelocityTemplate.vm) is used.
• RestDocConstants.DOC_DEST_PATH - specifies a different destination output html file path.
• RestDocConstants.DOC_CSS_PATH - specifies a different css file path.
• RestDocConstants.VERSION - specifies the REST version (used by the current velocity template for the html title).

2. Running the doclet using -doclet command-line option:

• Add the -doclet and the –docletpath options declare the RestDoclet class as the doclet class in order to use it instead of the standard java Doclet.
• Add the –sourcepath option declares the controller classes path.
• Add custom options if needed:
  –velocityTemplateFilePath <path>
–docletDestdir <path>
–docletCss <path>
–restVersion <version>
  
• For more details refer to http://docs.oracle.com/javase/1.4.2/docs/tooldocs/javadoc/overview.html

3. Using maven javadoc plugin:

• Refer to the maven-javadoc-plugin at restful pom.xml.
• Change the doclet and sourcepath tags.
• If other options are needed, add the additionalJOption tag and specify each wanted option, For example: <additionalJOption>-restVersion ${project.version} -docletCss resources/restDoclet/restdoclet.css</additionalJOption>.

Copyright and license

Copyright (c) 2012 GigaSpaces Technologies Ltd. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.