Today I am going to talk about API documentation tools. Specifically the ones we use at Lateral to create our documentation. Now, I understand if you aren't enthused by API documentation, I get that. But a lot of people are. I am. People who make APIs are. So maybe you should be too. You don't want to be left behind not knowing what's possible with today's advanced API tools. What would you talk about at conferences? It'd be terrible. Imagine. You'd have no idea. Anyway… Here we go!
API Blueprint
We decided to use API Blueprint as the main specification format of our APIs. Swagger was pretty much the only other contender in this decision. We went with API Blueprint mainly because of Aglio, the tool that outputs HTML from the blueprint. It offers great templates out of the box and provided us with a solid starting point. Another reason was the ability to write the specification in readable Markdown. It's way easier to write than JSON. The API Blueprint gets converted to JSON by Drafter for the machine readable format so you get the best of both worlds.
In hindsight, Swagger may have been a better choice, purely because of the adoption and tooling around it. That said, I'm happy with the results we've achieved with API Blueprint. It's a young standard and there are many tools in active development around it. So I look forward to seeing how that develops.
Aglio
Aglio is a tool that takes an API Blueprint and converts it to HTML. Aglio is amazing, it's really fast, has a nice design by default and is extensible with custom themes. We created a custom theme to generate the HTML for our API documentation.
Drafter
Drafter is made by Apiary who define the API Blueprint spec. You specify an API Blueprint file and then Drafter converts it to a JSON object. This JSON object can then be fed to various tools that can parse API Blueprint JSON. You can read more about the JSON specification here.
Httpsnippet
httpsnippet is an awesome tool by Mashape that takes HAR files and generates code snippets for various languages. When I was initially creating the documentation I was searching for a tool that did exactly what httpsnippet does. They hadn't released it when I had just started writing the documentation but funnily enough an early version of our NewsBots alerted me to the project!
Custom tools
All these tools need a bit of glue. We wrote a couple of scripts to facilitate an automated journey from Markdown API Blueprint to generated HTML and code snippets.
We use a Ruby script to convert the JSON generated from the API Blueprint into HAR files - check out the source here. At the moment the script doesn't take any headers because we don't use them much in our API. It's quite tailored to our set up but it wouldn't be hard to modify it to make it more general. If there's interest in a more general API Blueprint to HAR converter then I'd definitely be open to creating one.
And we have a shell script that automates the whole process. You can see it here, it's nothing special; it calls Algio to generate the HTML for the navigation menu and the main documentation, then it generates the JSON for the blueprint using Drafter, it then converts the blueprint JSON to multiple HAR files which are finally fed into httpsnippet which generates the code snippets.
Here is a diagram that shows the overall path from API Blueprint to our documentation:
The tooling we've chosen to generate our documentation is specific to us. There's definitely no right or wrong way. There is an abundance of open source API tooling available. This can make settling on a solution quite difficult. I would recommend deciding on a solution that works for your requirements and sticking with it. If there comes a point where you can't find a tool that does what you need to do, then create it and open source it!
