DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
View Events Video Library
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Integrating PostgreSQL Databases with ANF: Join this workshop to learn how to create a PostgreSQL server using Instaclustr’s managed service

Mobile Database Essentials: Assess data needs, storage requirements, and more when leveraging databases for cloud and edge applications.

Monitoring and Observability for LLMs: Datadog and Google Cloud discuss how to achieve optimal AI model performance.

Automated Testing: The latest on architecture, TDD, and the benefits of AI and low-code tools.

Related

  • Extending Swagger and Spring Doc Open API
  • REST-API Versioning Strategies
  • How to Automatically Detect Multiple Cybersecurity Threats from an Input Text String in Java
  • Building a Flask Web Application With Docker: A Step-by-Step Guide

Trending

  • CAN Bus: How It Works, Pros and Cons, and Fast Local Processing Tutorial
  • What Is a Flaky Test?
  • Unveiling Vulnerabilities via Generative AI
  • API Design
  1. DZone
  2. Data Engineering
  3. Databases
  4. Publish JavaDoc API Documentation when Releasing from Jenkins

Publish JavaDoc API Documentation when Releasing from Jenkins

Ivan K user avatar by
Ivan K
·
Apr. 08, 14 · Tutorial
Like (0)
Save
Tweet
Share
20.94K Views

Join the DZone community and get the full member experience.

Join For Free

this article describes how to publish javadoc api documentation for a maven project built on jenkins when that project is released. the javadoc api documentation is published using the same instance of apache tomcat 7 that jenkins runs on.

motivation

i wanted to, using the simplest way possible, publish javadoc api documentation for releases of a certain software component and make it available at a url unique to each version. in addition, i wanted to make the possible to list the different versions of the software component for which documentation is available.
the software component is built using maven and releases are made from a jenkins server.

required jenkins plug-ins

the following plug-ins need to be installed in jenkins in order to be able to complete the example in this article:

  • the appropriate plug-in for the source code management system you use.
    in this article i will use git, but any other source code management system works equally well as long as there is a jenkins plug-in available for it.
  • maven project plug-in.
    enables the creation of maven 2/3 jobs in jenkins.
  • jenkins m2 release plug-in
    also know as the maven release plug-in, which enables the performing of maven releases from a jenkins job.

prepare apache tomcat

the following steps prepares a special web application, the documentation web application, in apache tomcat 7 to which javadoc api documentation will be published. it is assumed that the directory containing the web applications deployed to tomcat resides in the webapps directory in the tomcat installation directory.

  • in the webapps directory in the tomcat home directory, create a directory for the documentation web application.
    in this example, i name my directory “api-documentation”, but you are of course free to choose any name you find appropriate.
  • in the documentation web application directory, create a web-inf directory.
  • in the web-inf directory created in the previous step, create a file named “web.xml”.
    the resulting directory structure should look like in the following picture:

tomcat directory structure

  • paste the following into the web.xml file created in the previous step:
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
    configures the default servlet to allow directory listings for the
    documentation web application.
-->
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"
  xsi:schemalocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
  version="3.0">
    <servlet>
        <servlet-name>default</servlet-name>
        <servlet-class>org.apache.catalina.servlets.defaultservlet</servlet-class>
        <init-param>
            <param-name>debug</param-name>
            <param-value>0</param-value>
        </init-param>
        <init-param>
            <param-name>listings</param-name>
            <param-value>true</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!--
        start of security configuration.
        this section can be removed if no security is required for api documentation.
    -->
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>api documentation root</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <!--
                this role must be present in the tomcat-users.xml file.
                the username and password to enter when accessing api documentation is the
                username and password of any user belonging to this role.
            -->
            <role-name>manager-gui</role-name>
        </auth-constraint>
    </security-constraint>

    <login-config>
        <auth-method>basic</auth-method>
        <realm-name>api documentation</realm-name>
    </login-config>

    <security-role>
        <description>the role that is required to access the api documentation</description>
        <!--
            this role must be present in the tomcat-users.xml file.
            the username and password to enter when accessing api documentation is the
            username and password of any user belonging to this role.
        -->
        <role-name>manager-gui</role-name>
    </security-role>
    <!-- end of security configuration. -->
</web-app>

the above web application configuration file configures the tomcat default servlet to allow directory listings. since the configuration file is located in a specific web application, directory listings will only be allowed in that particular web application.
in addition, security is configured, requiring login before being able to view api documentation. note that the role specified in the element must be defined in the tomcat-users.xml file. removing the indicated security configuration section removes security constraints for api documentation.

please refer to the web.xml file in the conf directory in the apache tomcat 7 directory for information on the different configuration alternatives available for the default servlet.

configure the maven project

assuming that the software component for which i want to publish javadoc api documentation for already is a maven project, i still need to ensure the following:

  • javadoc api documentation is created for the software component.
  • the javadoc api documentation is created at the correct location to allow for deployment by the maven site plug-in.
    that is, i want the documentation to be located in the site directory in the target directory of the maven project, not directly under the target directory of the project.
  • documentation is not published in by every build.
    since i only want to preserve documentation for release builds, i need to be able to control when documentation is published.
  • documentation is published to the appropriate location.
    i expect that i want to publish javadoc api documentation for multiple software components in the future. i also want to be able to publish documentation for different versions of a software component.

the following maven pom.xml file contains configuration to create and publish javadoc. parts not relevant to the creation of documentation have been omitted.

<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">

    ...

    <!--
        determines to which repository releases of the project are deployed.
        in this example, artifacts are deployed to a directory on the
        same computer on which the jenkins build server is run.
        note that this is just the minimal configuration required in order
        to be able to perform a maven release, not recommended for production.
        reference: http://maven.apache.org/pom.html#distribution_management
    -->
    <distributionmanagement>
        <repository>
            <uniqueversion>false</uniqueversion>
            <id>home1</id>
            <name>home repository</name>
            <url>file://c:/myprojectdeploydirectory/</url>
            <layout>default</layout>
        </repository>
    </distributionmanagement>

    <!--
        scm configuration is necessary in order to enable maven to manage
        the version of the project when releasing a new version on the
        jenkins build server.
        the configuration varies depending on which provider is used
        (for example, git, subversion, etc).
        in this example, git is used.
        reference: http://maven.apache.org/pom.html#scm
    -->
    <scm>
       <connection>scm:git:file://localhost/c:/gitrepo/myproject/</connection>
       <developerconnection>scm:git:file://localhost/c:/gitrepo/myproject/</developerconnection>
       <tag>head</tag>
    </scm>

    <properties>
        <!--
            path to the root directory of the documentation web application.
            this example assumes that the documentation web application
            is located in the same tomcat instance as the jenkins build
            server runs.
        -->
        <release.javadoc.root.path>[path to tomcat home]/webapps/api-documentation/</release.javadoc.root.path>

        ...
    </properties>

    ...

    <profiles>
        <!--
            profile for generation and publishing of release javadoc
            documentation.
            use: mvn -p releasedocumentation site
            references: http://maven.apache.org/guides/introduction/introduction-to-profiles.html
        -->
        <profile>
            <!-- 
                name of the maven build profile.
                used in project's jenkins job configuration.
            -->
            <id>releasedocumentation</id>
            <build>
                <plugins>
                    <!--
                        in preparation of site generation, extract the release
                        version number to a maven property.
                        performed during pre-site phase.
                    -->
                    <plugin>
                        <groupid>org.codehaus.mojo</groupid>
                        <artifactid>build-helper-maven-plugin</artifactid>
                        <version>1.8</version>
                        <executions>
                            <execution>
                                <phase>pre-site</phase>
                                <id>regex-property</id>
                                <goals>
                                    <goal>regex-property</goal>
                                </goals>
                                <configuration>
                                    <name>release_version</name>
                                    <value>${project.version}</value>
                                    <regex>-snapshot</regex>
                                    <replacement />
                                    <failifnomatch>false</failifnomatch>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                    <!--
                        javadoc generation.
                        javadoc is generated during pre-site phase.
                    -->
                    <plugin>
                        <groupid>org.apache.maven.plugins</groupid>
                        <artifactid>maven-javadoc-plugin</artifactid>
                        <version>2.9.1</version>
                        <executions>
                            <execution>
                                <phase>pre-site</phase>
                                <goals>
                                    <goal>javadoc</goal>
                                </goals>
                            </execution>
                        </executions>
                        <configuration>
                            <show>private</show>
                        </configuration>
                    </plugin>
                    <!--
                        copy javadoc to publish directory.
                        performed during the site phase.
                        if changing the phase, make sure that copying the
                        documentation is performed after having generated
                        the javadoc.
                    -->
                    <plugin>
                        <groupid>org.apache.maven.plugins</groupid>
                        <artifactid>maven-resources-plugin</artifactid>
                        <version>2.6</version>
                        <executions>
                            <execution>
                                <id>copy-resources</id>
                                <phase>site</phase>
                                <goals>
                                    <goal>copy-resources</goal>
                                </goals>
                                <configuration>
                                    <generateprojectinfo>false</generateprojectinfo>
                                    <generatereports>false</generatereports>
                                    <outputdirectory>${release.javadoc.root.path}${project.artifactid}-${release_version}/</outputdirectory>
                                    <resources>
                                        <resource>
                                            <directory>${project.build.directory}/site/</directory>
                                            <filtering>true</filtering>
                                        </resource>
                                    </resources>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
            <!--
                include this section to disable, or configure, generation
                of project info report(s).
                in this case, all project info reports have been disabled.
            -->
            <reporting>
                <plugins>
                    <plugin>
                        <groupid>org.apache.maven.plugins</groupid>
                        <artifactid>maven-project-info-reports-plugin</artifactid>
                        <version>2.7</version>
                        <reportsets>
                            <reportset>
                                <reports>
                                </reports>
                            </reportset>
                        </reportsets>
                    </plugin>
                </plugins>
            </reporting>
        </profile>
    </profiles>
</project>

note that:

  • the element is required, in order for maven to know to which repository to deploy project artifacts when performing a release.
    this example shows a minimal configuration, using a local directory as target, which is not recommended for production.
  • it is not possible to use the element to specify where to publish the documentation, since this configuration is evaluated before we are able to set maven properties using the maven build helper plug-in.
  • the element specifies where the project is located in the source-code management system.
    this configuration is necessary, in order for maven to be able to update the project version number when performing a release. this configuration depends on the source-code management system used (example: subversion, git, perforce etc).
    in this example, the git source-code management system is used with the git repository residing in a local directory.
  • in the <properties> element, a maven property named “release.javadoc.root.path” is defined.
    this property specifies the local directory to which release javadoc documentation will be copied. the string “[path to tomcat home]” needs to be replaced with the path to the tomcat installation directory, or the directory that contains the webapps directory used by tomcat if it is not present in the tomcat directory.
  • in the <profiles> element, a maven build profile named “releasedocumentation” is defined.
    this is the maven build profile that determines what happens when release javadoc documentation is to be produced and published.
  • the first plug-in in this profile is the maven build helper plug-in.
    it is used to remove the “-snaphot” part of the version number of the software component and store the result in the maven property “release_version”.
    it is difficult to intercept the workings of the maven release plug-in at a stage where the release version number is available, so this strategy was chosen to keep the maven configuration simpler.
  • the maven build helper plug-in is configured to execute during the maven pre-site phase.
    this in order to be part of the maven site goal which we will use to create and publish the javadoc documentation.
  • the maven javadoc plug-in is used to generate the javadoc.
    no surprise here, except that the execution phase is set to pre-site. as with the maven build helper plug-in, in order to be part of the maven site goal which we will use to create and publish the javadoc documentation.
  • the maven resources plug-in is used to copy (publish) the javadoc documentation to the api-documentation web application in tomcat.
    this plug-in will execute during the maven site phase. the site phase executes after the pre-site phase and this ensures that the javadoc has been created and that the maven “release_version” property has been set.

to generate and publish javadoc documentation for the software component, we can now issue the following command:

mvn -p releasedocumentation site

configure the jenkins job

to generate and publish documentation as part of a maven release performed in jenkins, we need to include the above maven property and goal in the release goals of the jenkins job for the software component.
in my case the build environment section of the job configuration looks like this:

jenkins job configuration remember to save the job configuration after you have made the changes!

view project javadoc

now when i perform a maven release from jenkins, the documentation is published and i can browse the documentation available for the different software components and their different versions by opening the url http://localhost:8080/api-documentation/ in my browser and then drill down into the appropriate directory.

on the first page you will see a list of the projects and versions for which javadoc have been published:

api documentation root

click the link for the project and version which javadoc you want to view. in my example i click the link for version 1.0.5 of the jmsrequestreply project:

api documentation project

click the “apidocs” link to view the javadoc.

Documentation Javadoc Jenkins (software) Apache Tomcat Apache Maven Directory API Web application Release (agency) Management system

Published at DZone with permission of Ivan K. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • Extending Swagger and Spring Doc Open API
  • REST-API Versioning Strategies
  • How to Automatically Detect Multiple Cybersecurity Threats from an Input Text String in Java
  • Building a Flask Web Application With Docker: A Step-by-Step Guide

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends: