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

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

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 →

22 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
  • Hi Petri,
    Can we do this transformation of raml2html using Java or spring boot ? I see this includes node.js scripting. Also we use gradle for adding dependencies.

    Reply
    • Hi,

      There is a project called: RAML Java Parser, but I have never used it myself. In theory, you should be able to parse RAML documents with it.

      Reply
      • Thanks for your reply. Do we have a gradle plugin for raml2html?

        Reply
  • Hi, I have more than one raml files and included files.. how can we generate multiples files in one go using single pom.xml.. and run command line mvn clean package or using eclipse?

    Can you please share some pom.xml example that will be a gr8 help.. like below

    package

    exec

    raml2html
    -i src/docs/api.raml -o target/api.html

    Reply
    • As far I know, you cannot generate multiple files in one go by using the technique described in this blog post because raml2html seems to support only one input file :( The sad thing is that I couldn’t find anything helpful from Google either. I assume that you have create a custom JS script that uses raml2html and run that script by using the Exec Maven plugin.

      Reply
  • I am getting this error when i tried using this plugin – Command execution failed. Cannot run program “raml2html”

    Reply
    • Did you install NPM and raml2html before you tried to use this plugin?

      Reply
      • Yes i have installed NPM and raml2html locally

        Reply

Leave a Comment