RAML: THE RESTFUL API MODELING LANGUAGE (PART 10)

Generating API Documentation:

RAML is a very detailed, unambiguous overview of an API, but it’s not terribly user-friendly for our API’s consumers.

However because it’s a well-defined, open format, there are tools which can help us use this information in a more user-friendly way. Most notably, there are tools which will take our RAML files and produce HTML-based documentation, ready to be published on the Web.

Let’s look at a few.

Converting RAML to HTML

raml2html

The raml2html tool, as the name suggests, can convert your RAML files into HTML documentation.

Here’s a screenshot of what it looks like out-of-the-box:

To use it, first install it via npm:

npm i -g raml2html

Then, to convert a RAML file to HTML you simply do this:

raml2html api.raml > index.html

The result is a fairly reasonable set of API documentation. It has certain dependencies – such as JQuery and Bootstrap – which it pulls in from a CDN, but of course you can modify the resulting HTML as you see fit. You can create your own templates, if you prefer, and simply specify them via the command-line:

raml2html -t custom-template.handlebars -r custom-resource.handlebars -m custom-item.handlebars -i example.raml -o example.html

There’s also a Grunt plugin and a Gulp plugin to make it even easier to generate documentation.

There are certain limitations. Security information doesn’t get copied into the HTML, so if you use OAuth for example, you may need to document that separately yourself.

php-raml2html

There’s also a PHP equivalent called php-raml2html.

Here’s a screenshot of the tool’s output:

There’s also an online demo, and you’ll find the documentation here.

Personally, I prefer raml2html for two reasons. First, the default output is a little cleaner. Second, it produces static HTML – whereas php-raml2html requires PHP to run – which means it’s perfect for hosting on Github Pages or the like. However, if you’re primarily a PHP developer then you might find this tool easier to customize.