I released the starter package of my Test With Spring course. Take a look at the course >>

Generating HTML Documentation From RAML Documents With Maven

api robot sign

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

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:

  1. Add the Exec Maven Plugin into the plugins section of our pom.xml file.
  2. Create an execution that invokes the plugin’s exec goal when the package phase of the Maven default lifecycle is invoked.
  3. Ensure that the Exec Maven Plugin executes the raml2html application.
  4. 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:

<build>
	<plugins>
		<plugin>
			<groupId>org.codehaus.mojo</groupId>
			<artifactId>exec-maven-plugin</artifactId>
			<version>1.4.0</version>
			<executions>
				<execution>
					<phase>package</phase>
					<goals>
						<goal>exec</goal>
					</goals>
				</execution>
			</executions>
			<configuration>
				<executable>raml2html</executable>
				<commandlineArgs>-i src/docs/api.raml -o target/api.html</commandlineArgs>
			</configuration>
		</plugin>
	</plugins>
</build>
Additional Reading:

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:

RAMP_API_HTML

Let’s summarize what we learned from this blog post.

Summary

This blog post has taught us two things:

  • We can transform RAML documents into HTML by using raml2html.
  • We can invoke raml2html during our Maven build by using the Exec Maven Plugin.

P.S. You can get the example application of this blog post from Github.

About the Author

Petri Kainulainen is passionate about software development and continuous improvement. He is specialized in software development with the Spring Framework and is the author of Spring Data book.

About Petri Kainulainen →

13 comments… add one
  • I’m interested in RAML but haven’t found a way to generate it from annotations as one may with Swagger. Any suggestions?

    Reply
    • If you want to generate your API documentation from annotations, you should use Swagger. The whole idea of RAML is that developers describe their APIs by using YAML-based language that can be transformed into different document formats.

      Reply
  • The command line arguments of the maven plugin has a bug, it says “The first line must be: ‘#%RAML 0.8′” every while I try to generate the documentation. When you use raml2html command from bash using the same command line arguments, the process works

    Reply
    • This error message is actually a raml2html error and it means that the first line of RAML document is not:

      
      #%RAML 0.8
      
      

      If I remove this line from the example RAML document, I see the same error when I run the build.

      I don’t know why you don’t see the error message if you run the raml2html command manually. If I try to run the same command at command prompt after I have removed the first line of the example RAML document, I see the same error message.

      Maybe you are using a different raml2html version. I am using raml2html 2.1.2.

      Reply
  • Hi,
    do you know how to test the Raml to HTML conversion process so that we can see that a Raml file gets transformed into the expected HTML?.

    Reply
    • Hi,

      Well, if you want to do this, you could create the API documentation when the compile phase of the Maven default lifecycle is invoked, and write a unit tests which ensures that the HTML document was created. However, I am not sure if it makes sense to do this because this means that the raml2html command is invoked every time when you compile your code.

      Reply
  • Hello,

    Could you please tell me if there is a way to generate html from raml without installing node and raml2html tools ?

    Thanks in advance

    Reply
    • Hi,

      The raml.org website has a list of tools that help you to “visualize” your API documentation (RAML document). You can see this list by clicking this link and clicking the “documentation” link found from left sidebar.

      Reply
  • Hi,
    I actually would like to automate the generation of html file on servers where node, npm and raml2html are not installed, i looked for a maven dependency to do that but i found nothing
    any help would be apreciated

    Reply
    • Hi,

      Unfortunately I am not aware of such Maven plugin :( Did you check out the list which I mentioned in my previous comment?

      Reply
  • Hi Petri,
    Thanks for your responses, i have already seen that list but it wasn’t what i was looking for
    Fortunately i found what i need here https://mvnrepository.com/artifact/de.androbit/raml-converter-maven-plugin (Git repo)

    The rendering is a bit poor than with raml2html but it works

    And here is my configuration

    Update: I removed the configuration since WP removed all XML elements from it – Petri

    Reply
    • Hi,

      I am happy to hear that you were able to solve your problems.

      Reply

Leave a Comment