How to Generate HTML JavaDoc Reporting with Maven

This example explains how you can Generate HTML JavaDoc in your build using maven. HTML JavaDocs can be automatically created by the maven-javadoc plugin which uses the javadoc executable located in $JDK_HOME/bin/ directory. Generating this HTML JavaDoc is really interesting if you decide to open-source your project. Then you can show the whole world how awesome your project really is.

Create a simple User POJO

Lets create a simple POJO as an example JavaDoc candidate.

/**
 * User object
 */
public class User {

    private Integer id;
    private String username;
    private String password;
    private String email;

    /**
     * Creates a new user
     * @param username unique username of the user
     * @param password password of the user
     * @param email email address of the user
     */
    public User(String username, String password, String email) {
        this.username = username;
        this.password = password;
        this.email = email;
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

Create a User Service

For the example we also create a simple UserService interface for JavaDoc purposes.

/**
 * This service will handle all the user interactions
 */
public interface UserService {

    /**
     * This method will register a user
     * @param user user that will be registered
     */
    void register(User user);

    /**
     * Fetches a user with a given Identifier
     * @param id unique identifier of a user
     * @return User Object
     */
    User fetchUser(Integer id);
}

Generate HTML JavaDoc using Maven

In order to Generate HTML JavaDoc using maven we must register the maven-javadoc plugin in the reporting element. This will tell maven to generate HTML JavaDoc in the site phase. Secondly I also added the maven-project-info-reports-plugin because maven issued a warning that the required version could not be found. But this should work without this plugin also.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>com.memorynotfound.maven.plugin.javadoc</groupId>
    <artifactId>generate-javadoc-html</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <url>http://memorynotfound.com</url>
    <name>MAVEN - ${project.artifactId}</name>
    <description>This project will generate html javadoc using maven</description>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    </properties>

    <reporting>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>2.10.3</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-project-info-reports-plugin</artifactId>
                <version>2.8</version>
            </plugin>
        </plugins>
    </reporting>

</project>

Execute maven goals

Lets build the reports using mvn clean site.

mvn clean site

Output

[INFO] Scanning for projects...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building MAVEN - generate-javadoc-html 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ generate-javadoc-html ---
[INFO] Deleting /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target
[INFO] 
[INFO] --- maven-site-plugin:3.3:site (default-site) @ generate-javadoc-html ---
[INFO] configuring report plugin org.apache.maven.plugins:maven-javadoc-plugin:2.10.3
[INFO] 
[INFO] >>> maven-javadoc-plugin:2.10.3:aggregate (report:aggregate) > generate-sources @ generate-javadoc-html >>>
[INFO] 
[INFO] <<< maven-javadoc-plugin:2.10.3:aggregate (report:aggregate) < generate-sources @ generate-javadoc-html <<<
[INFO] 
[INFO] >>> maven-javadoc-plugin:2.10.3:javadoc (report:javadoc) > generate-sources @ generate-javadoc-html >>>
[INFO] 
[INFO] <<< maven-javadoc-plugin:2.10.3:javadoc (report:javadoc) < generate-sources @ generate-javadoc-html <<<
[INFO] 
[INFO] >>> maven-javadoc-plugin:2.10.3:test-aggregate (report:test-aggregate) > generate-test-sources @ generate-javadoc-html >>>
[INFO] 
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ generate-javadoc-html ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 0 resource
[INFO] 
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ generate-javadoc-html ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 2 source files to /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/classes
[INFO] 
[INFO] <<< maven-javadoc-plugin:2.10.3:test-aggregate (report:test-aggregate) < generate-test-sources @ generate-javadoc-html <<<
[INFO] 
[INFO] >>> maven-javadoc-plugin:2.10.3:test-javadoc (report:test-javadoc) > generate-test-sources @ generate-javadoc-html >>>
[INFO] 
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ generate-javadoc-html ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 0 resource
[INFO] 
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ generate-javadoc-html ---
[INFO] Nothing to compile - all classes are up to date
[INFO] 
[INFO] <<< maven-javadoc-plugin:2.10.3:test-javadoc (report:test-javadoc) < generate-test-sources @ generate-javadoc-html <<<
[INFO] configuring report plugin org.apache.maven.plugins:maven-project-info-reports-plugin:2.8
[INFO] Relativizing decoration links with respect to project URL: http://memorynotfound.com
[INFO] Rendering site with org.apache.maven.skins:maven-default-skin:jar:1.0 skin.
[INFO] Skipped "JavaDocs" report, file "apidocs/index.html" already exists for the English version.
[INFO] Skipped "JavaDocs" report, file "apidocs/index.html" already exists for the English version.
[INFO] Generating "JavaDocs" report    --- maven-javadoc-plugin:2.10.3
[INFO] 
Loading source file /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/src/main/java/User.java...
Loading source file /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/src/main/java/UserService.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_67
Building tree for all the packages and classes...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/User.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/UserService.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/package-frame.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/package-summary.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/package-tree.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/constant-values.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/class-use/User.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/class-use/UserService.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/package-use.html...
Building index for all the packages and classes...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/overview-tree.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/index-all.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/deprecated-list.html...
Building index for all classes...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/allclasses-frame.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/allclasses-noframe.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/index.html...
Generating /memorynotfound/java/tutorials/maven/plugins/maven-javadoc-plugin/generate-javadoc-html/target/site/apidocs/help-doc.html...
[INFO] Generating "Dependency Convergence" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "Dependency Information" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "About" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "Plugin Management" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "Project Plugins" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "Project Summary" report    --- maven-project-info-reports-plugin:2.8
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5.240 s
[INFO] Finished at: 2015-04-21T19:08:13+02:00
[INFO] Final Memory: 32M/452M
[INFO] ------------------------------------------------------------------------

Example pages

generate html javadoc maven projectgenerate html javadoc maven user objectgenerate html javadoc maven user service

References

Download

You may also like...