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:

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.

26 comments… add one
  • B. K. Oxley (binkley) Dec 24, 2015 @ 14:18

    I'm interested in RAML but haven't found a way to generate it from annotations as one may with Swagger. Any suggestions?

    • Petri Dec 25, 2015 @ 17:35

      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.

  • German Aug 5, 2016 @ 23:48

    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

    • Petri Aug 6, 2016 @ 12:23

      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.

  • Purnima Aug 25, 2016 @ 15:45

    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?.

    • Petri Sep 5, 2016 @ 21:05

      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.

  • Sayamon Dec 19, 2016 @ 15:12

    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

    • Petri Dec 19, 2016 @ 21:15

      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.

  • Sayamon Dec 19, 2016 @ 15:14

    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

    • Petri Dec 19, 2016 @ 21:16

      Hi,

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

  • Anonymous Dec 26, 2016 @ 13:26

    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

    • Petri Dec 29, 2016 @ 8:02

      Hi,

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

  • Banu Mar 9, 2017 @ 16:42

    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.

    • Petri Mar 9, 2017 @ 18:44

      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.

  • Dhanunjay Apr 26, 2017 @ 21:37

    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

    • Petri Apr 26, 2017 @ 22:12

      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.

  • Dipak May 19, 2017 @ 23:14

    I am getting this error when i tried using this plugin - Command execution failed. Cannot run program "raml2html"

    • Petri May 19, 2017 @ 23:25

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

      • Dipak May 21, 2017 @ 7:19

        Yes i have installed NPM and raml2html locally

  • Ellie Nov 27, 2019 @ 10:05

    Can you elaborate more on the second and third steps of the configuration? What exactly we should do?

    • Petri Dec 1, 2019 @ 20:28

      Hi,

      You should specify the executed command/program (raml2html) and ensure that the Exec Maven plugin executes it in a separate process (the exec goal takes care of this).

      Also, you must also identify the Lifecycle phase in which the API documentation is generated (the raml2html application is run). If you aren't familiar with the Maven lifecycle, you should take a look at the Maven documentation.

  • praveen Aug 2, 2022 @ 0:46

    Hi,
    I have multiple Controller which contain multiple API in my applications so do we need to write multiple .rmal file.

    • Petri Aug 8, 2022 @ 10:15

      Hi,

      I haven't used RAML for a while, but if I remember correctly, RAML encourages you to split your API specification into as many pieces as possible, it doesn't force you to do so. In other words, you can use the approach that makes sense to you.

Leave a Reply