How we build our API documentation

If you have ever used APIs you know that good documentation is important. It should also always be up-to-date. In this post I’m not going to discuss how to write documentation and what is required, but rather which tools we use to get the documentation updated as quickly as possible on our developer portal (developer.leaseweb.com).

We employ a number of different tools to help with the process.

1. RAML (raml.org)

Good documentation starts with good specifications. For this we have decided to use RESTful API Modeling Language (RAML) (created by MuleSoft), together with tools like raml2html (https://github.com/raml2html/raml2html) for creating HTML. Using templates, we can create the HTML as we need it for further processing. Within the RAML specifications, we give descriptions to each endpoints that will become the documentation a user can see on the site.

We already had experience with RAML, which made our choice easy, but there are other tools/specifications around that can do the same. Swagger (swagger.io) is probably the largest and most supported framework around.

2. Httpsnippet (https://github.com/Mashape/httpsnippet)

All developer documentation needs to have code examples. Instead of writing our own code examples, we use httpsnippet, a tool by Mashape that generates code examples for many languages and tools. From the RAML specification we generate a HAR format that httpsnippet uses to create really nice code snippets.

3. Jekyll (com)

Jekyll is an awesome tool for easily creating static websites. We write most of our pages in Markdown (combined with some HTML) and Jekyll generates the static site. By using templating you can make sure your site has a consistent look and feel. Once we have generated the static site, we only need to ship the content to our production server.

4. HTMLProofer (https://github.com/gjtorikian/html-proofer)

With HTMLProofer we do some validation on the output created by Jekyll. For example, we sometimes link to other sites and want to make sure that all links are still valid. Using HTMLProofer we can capture most HTML errors before we put the documentation online.

Together with Bitbucket and Jenkins, we are able to automatically update our developer portal. Once an API specification is updated and the pull-request is merged, Jenkins will build the static site, do some validation on the output and push the site to our production servers. All of this occurs within a minute after merging.

We are currently working on a new developer site, something we plan to open-source in the future. Stay tuned!