Generating HTML Documentation From RAML Documents With Maven

The RESTful API Modeling Language (RAML) is a YAML-based language that is used for describing REST(ful) APIs.

I like the RAML syntax because it’s text based, versatile, and easy to use.

However, when I publish a REST API, I must provide readable API documentation or no one will use my API.

This blog post describes how can we solve that problem. We will learn how we can generate HTML documentation from RAML documents by using Maven.

Let’s start by installing the required tools.

If you are not familiar with RAML and you want to learn more about it, you should read the following tutorials:

Installing the Required Tools

We can transform RAML documents into HTML by using an utility called raml2html. We can install it by following these steps:

First, the easiest way to install raml2html is to use NPM. In other words, we have to install NPM before we can install raml2html. We can do this by following the instructions given by the Node.js reference documentation.

If you are using OS X, I recommend that you install Node.js by using Homebrew.

Second, after we have installed Node.js, we can install raml2html. Because we want to use it as a command line tool, we have to install it globally. We can do this by running the following command at the command prompt:

npm install -g raml2html

Additional Reading:

Installing NPM Packages Globally

After we have installed raml2html, we can generate HTML from a single RAML document by running the following command at the command prompt:

raml2html -i [input file path] -o [output file path]

We have now installed all the required tools. Let’s move on and configure our Maven build.

Configuring Our Maven Build

Our next step is to invoke the raml2html application with Maven. We want to invoke the raml2html application when we package our Maven project because this way it doesn’t cause unnecessary delays to compilation or unit testing.

We can configure our Maven build by following these steps:

Add the Exec Maven Plugin into the plugins section of our pom.xml file.
Create an execution that invokes the plugin’s exec goal when the package phase of the Maven default lifecycle is invoked.
Ensure that the Exec Maven Plugin executes the raml2html application.
Configure the location of the input file (src/docs/api.raml) and the location of the output file (target/api.html).

The build section of our pom.xml file looks as follows:

 1<build>
 2	<plugins>
 3		<plugin>
 4			<groupId>org.codehaus.mojo</groupId>
 5			<artifactId>exec-maven-plugin</artifactId>
 6			<version>1.4.0</version>
 7			<executions>
 8				<execution>
 9					<phase>package</phase>
10					<goals>
11						<goal>exec</goal>
12					</goals>
13				</execution>
14			</executions>
15			<configuration>
16				<executable>raml2html</executable>
17				<commandlineArgs>-i src/docs/api.raml -o target/api.html</commandlineArgs>
18			</configuration>
19		</plugin>
20	</plugins>
21</build>

Additional Reading:

Exec Maven Plugin

We can now create the HTML API documentation by running the following command at the command prompt:

mvn clean package

This transforms the src/docs/api.raml file into HTML and writes the created HTML to the target/api.html file. The API documentation of our example application looks as follows: