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.
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.
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:
- 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:
<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>
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:
Let's summarize what we learned from this blog post.
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.
I'm interested in RAML but haven't found a way to generate it from annotations as one may with Swagger. Any suggestions?
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.
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
This error message is actually a raml2html error and it means that the first line of RAML document is not:
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
raml2htmlcommand 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.
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?.
Well, if you want to do this, you could create the API documentation when the
compilephase 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
raml2htmlcommand is invoked every time when you compile your code.
Could you please tell me if there is a way to generate html from raml without installing node and raml2html tools ?
Thanks in advance
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.
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
Unfortunately I am not aware of such Maven plugin :( Did you check out the list which I mentioned in my previous comment?
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
I am happy to hear that you were able to solve your problems.
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.
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.
Thanks for your reply. Do we have a gradle plugin for raml2html?
Take a look at Gradle RAML Plugin.
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
-i src/docs/api.raml -o target/api.html
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.
I am getting this error when i tried using this plugin - Command execution failed. Cannot run program "raml2html"
Did you install NPM and raml2html before you tried to use this plugin?
Yes i have installed NPM and raml2html locally
Can you elaborate more on the second and third steps of the configuration? What exactly we should do?
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.
I have multiple Controller which contain multiple API in my applications so do we need to write multiple .rmal file.
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.