SpringDoclet

SpringDoclet is an extension to Javadoc utility (Doclet) which generates web API documentation for backends based on Spring Web MVC framework: http://static.springsource.org/spring/docs/current/spring-framework-reference/html/mvc.html.

Output documentation structure

Index file structure

Package title (package fully qualified name)

• Controller title (controller simple name)

Package title will be taken from standard package description file (package.html, package-info.html or package-info.java). Controller title will be taken from controller class Javadoc comment

Controller file structure

Controller title (controller simple name)

• METHOD: /url/
  (from @RequestMapping annotation)

  Description
  (from method Javadoc comment)

  Access rights:
  (from @RolesAllowed annotation)

  • Role1
  • Role2

  Input parameters:
  | Parameter name | Type | Required? | Description |
  (from Javadoc comment and @param tag and from @RequestParam/@PathVariable annotations)

  Return object:
  | Field name | Type | Description |
  (from return class fields Javadoc comments)

  Errors:
  | Exception type | Description |
  (from Javadoc @throws tag. If tag description is empty description will be taken from exception class Javadoc)

Documentation example

/**
 * Articles
 */
@Controller
@RolesAllowed("ROLE_MANAGER")
public class ArticleController {

    /* ... */

    // ========================================================================

    /**
     * Creates a new article
     */
    @ResponseBody
    @RequestMapping(value = "/article", method = RequestMethod.POST)
    public GetArticlesResponse createArticle(
            @RequestBody @Valid CreateArticleRequest request
    ) {
        /* ... */

        return new CreateArticleResponse();
    }

    public static class CreateArticleRequest {
        /** article title */
        @NotEmpty
        public String title;

        /** article author */
        public String author;

        /** article content */
        public String text;
    }

    public static class CreateArticleResponse {
        public String success = true;
    }

    // ========================================================================

    /**
     * Returns article list
     * @param page  page number
     * @param limit items per page
     * @throws InvalidPageNumberException if page number is invalid
     */
    @ResponseBody
    @RequestMapping(value = "/articles", method = RequestMethod.GET)
    public GetArticlesResponse getArticles(
            @RequestParam(value = "page", required = false) Integer page,
            @RequestParam(value = "limit", required = false) Integer limit
    ) throws InvalidPageNumberException {
        GetArticlesResponse response = new GetArticlesResponse();

        /* ... */

        return response;
    }

    public static class GetArticlesResponse {
        public static class Article {
            /** article ID */
            public Integer id;

            /** article title */
            public String title;

            /** article URI */
            public String uri;

            /** article content */
            public String text;
        }

        /** articles list */
        public List<Article> articles = new ArrayList<Article>();

        /** total articles count */
        public Long totalRecords;
    }

    // ========================================================================

    /* ... */
}

Configuration

See 'maven-javadoc-plugin' documentation: http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html Documentation can be built with javadoc:javadoc goal.

Additional parameters

-d	specifies output directory for generated documentation
-stylesheetfile	specifies stylesheet file which will be attached to generated documentation
-windowtitle <title>	sets window base title
-docencoding	sets output documentation encoding
-lang	sets template language (two-letter code)

Example

<project ...>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>2.8.1</version>
                <configuration>
                    <subpackages>org.springframework.samples.petclinic.web</subpackages>
                    <quiet>true</quiet>
                    <show>public</show>
                    <doclet>ru.hts.springwebdoclet.SpringWebDoclet</doclet>
                    <docletArtifacts>
                        <docletArtifact>
                            <groupId>ru.kliniki-online</groupId>
                            <artifactId>spring-web-doclet</artifactId>
                            <version>0.1.4</version>
                        </docletArtifact>
                    </docletArtifacts>

                    <!-- useStandardDocletOptions=false is required -->
                    <useStandardDocletOptions>false</useStandardDocletOptions>

                    <additionalparam>
                        -stylesheetfile style.css
                        -windowtitle "Web API"
                        -lang ru
                    </additionalparam>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

License

GNU General Public License, version 3 and better: http://www.gnu.org/copyleft/gpl.html