Skip to content
This repository has been archived by the owner on Jan 31, 2019. It is now read-only.
/ rest-doclet Public archive

Enables automatic generation of documentation from Spring MVC REST service source code.

Notifications You must be signed in to change notification settings

CloudifySource/rest-doclet

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

50 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Build Status

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).
  1. 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
  1. 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.

About

Enables automatic generation of documentation from Spring MVC REST service source code.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published