You’ll never guess which API documentation tools we use

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

api-blueprintWe 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

aglioAglio 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

drafterDrafter 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

http-snippethttpsnippet 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

harAll 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:

api-diagram

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!

The Author
Making stuff with computers at Lateral.
Comments

7 thoughts on “You’ll never guess which API documentation tools we use

  1. Thanks for sharing, Max. Love seeing how your team has glued everything together. The docs on Lateral look amazing.

    I’m a bit curious about your comment regarding Swagger. We’re trying to make final decisions on API Blueprint vs Swagger.

    > In hindsight, Swagger may have been a better choice, purely because of the
    > adoption and tooling around it.”

    Now that you’re several more months into your approach, does your statement about second guessing Swagger still hold true?

    1. Hey Jeff, thank you!

      I think the most important thing is to pick a format and stick with it. Essentially they do the same thing. I haven’t really dived in to the world of Swagger and the tooling around the format. The tools available for API Blueprint are pretty powerful and the list is growing rapidly: https://apiblueprint.org/#t

      We’re actually working on a new version of our documentation that will be released soon. It still uses API blueprint and we ended up writing a custom renderer in place of Aglio which works nicely. So I guess what I say about Swagger doesn’t hold true if you’re willing to develop your own tools. API blueprint is a younger format but I like the direction and design choices around it. So I’m happy with the choice to use API Blueprint!

      1. Max, thanks for this writeup. Super helpful. We started on Apiary but our documentation needs are larger. Getting code samples is important for us. Did you move to your new renderer? If so what additional tools are used if any? Or is it just a different Aglio renderer?

        1. Hi Ben, no problem, I’m glad it helped! We moved to a custom renderer. This basically uses the same method that aglio uses to render the blueprint and adds in the generation of the code snippets and other HTML (such as the navigation). It uses protagonist to parse the blueprint and then uses jade (now called pug) in order to render the JSON from protagonist into HTML. If you look at the source of aglio you’ll get an idea of how it works.

          It uses httpsnippet to render out code snippets for various languages. I include a link to that script in the post.

          And it uses Jade again to render the navigation and to render some markdown files as documentation.

          So basically we more or less use the same tools as mentioned in the blogpost but removed the aglio dependency in order to get more control over the flow of data and hook in things like the snippets and custom markdown documentation pages.

  2. Thanks for sharing. This tools is great one for API documentation, when using postman and swagger it’s really helpful. Recently I have seen another tools that is also save me time to generate the api documentation, you may also check it here: https://apidocgen.com/

Comments are closed.