How to build an API docs site using Slate

If you want to build a simple but attractive looking API documentation site, you can’t really go wrong with an open-source tool like Slate. Despite being created by a teenager developer during a summer internship, it has become an incredibly popular tool with the project being forked more than 15,000 times and with well-known organisations including NASABest Buy, Monzo and Skyscanner all using it.

🎬 So what is Slate?

Slate is a Ruby-based tool that generates a great-looking, three-panelled API documentation static site from a set of markdown files. It was built by developer Robert Lord in 2013 when he was an 18-year-old intern at at travel software company Tripit. He convinced his boss at the time to let him open-source the project and the rest is history.

He told me found it pretty surreal that so many people were now using and maintaining his “buggy project” nearly six years later. However, the results speak for themselves — you can see some examples in the Slate in the Wild repository.

🛠️ Before you Begin

So before you begin, make sure you have met the following requirements:

  • You have an Open API/ Swagger file in .yaml or .json format.
  • You have installed Node.js. This includes npm (Node Package Manager).
  • You have installed swagger-to-slate or widdershins (or similar) to convert your file into Markdown. I used the former in this example.
  • You have installed Vagrant and VirtualBox.

In this example, I’m going to use the generic Swagger Petstore example which I have saved to my Desktop and called petstore.yaml. To convert this to Markdown using swagger-to-slate, open a terminal and run:

swagger-to-slate -i ~/Desktop/petstore.yaml

This saves a file called petstore.md in the same location as the .yaml file. Once you have this, you can get started with Slate.

🔨 Build your site using Vagrant

To build your API documentation site using Vagrant, follow these steps:

  1. Go to the Slate repository on Github.
  2. Click Fork to create your own fork of the main repository.
  3. Clone the fork to your local machine using git clone. For example:git clone https://github.com/<your_github_username>/slate.git
  4. Go to ~/slate/source and remove the index.html.md file.
  5. Rename the Markdown file you created earlier as index.html.md and copy it into the source folder, changing the file locations as required:
    cp ~/<local_path>/index.html.md ~/<local_path>/slate/source/
  6. To build your site using Vagrant, run: vagrant up
  7. Go to http://localhost:4567 to see your site. It may take several minutes to build.

🐳 Build your site using Docker

You can also use Docker to create your site but you must edit some additional files. Although this method is not officially supported, I had no issues when I tried using it.

If you are using Ruby version 2.5.1 or newer, you will need to create three files:

  • .dockerignore :
    .git 
    source
  • Dockerfile :
    FROM ruby:2.5.1
    MAINTAINER Adrian Perez <adrian@adrianperez.org>
    VOLUME /usr/src/app/source
    EXPOSE 4567
    
    RUN apt-get update && apt-get install -y nodejs \
    && apt-get clean && rm -rf /var/lib/apt/lists/*
    
    CMD ["bundle", "exec", "middleman", "server", "--watcher-force-polling"]
  • docker-compose.yml :
    app:
      build: .
      ports:
        - 4567:4567
      volumes:
        - ./source:/usr/src/app/source

After you create these files, follow these steps:

  1. Add the Docker files to your local Slate directory.
  2. To build your Docker site run: docker-compose up
  3. Go to http://localhost:4567 to view your site.

For alternative Docker methods refer to this documentation.

💎 Build your site using Bundler

Alternatively, if you want to run your Slate site locally, you can also use Bundler. To use this method you must install Ruby version 2.3.1 or newer. To check which version you have installed run: ruby -v

If you need to install Ruby, see the installation documentation for the different methods available.

Once installed Ruby, you can install Bundler: gem install bundler

To build your API docs site using builder:

  1. Navigate to your Slate directory: cd slate
  2. Install the dependencies such as Middleman specified in the Slate Gemfile: bundle install
  3. Launch the Middleman static site generator: bundle exec middleman server
  4. Go to http://localhost:4567 to see your site.

That’s pretty much it! Good luck.

The Story behind Slate: An Interview with Robert Lord

Back in 2013, developer Robert Lord, then an 18-year-old intern at Tripit travel software company, was challenged to create an API documentation tool by his boss. It took him several weeks but the result was a beautiful, responsive API documentation generator called Slate. Five years later, it has grown into a popular open-source tool that is used by a number of global organisations and companies including NASA, IBM and Coinbase.

cover-image-for-above-the-entire-post
Robert Lord created Slate while interning at Tripit. Copyright© Concur Technologies,

Lord said the Slate project grew out of a set of requirements the Tripit engineering team had at the time. He said: “I was interning at TripIt and my boss pointed me towards some two-column documentation pages and said ‘We’d like a page like this for our new API.’ They also had the requirement that their technical writer could make changes, and I think they didn’t want to write raw HTML. I made a generator that ended up being pretty generic to any documentation, and convinced them to let me open source it.”

How to Use Slate

Slate is simple to use, you fork the Slate Github repository and create a clone. Next you customise the code to meet your requirements; adding a custom logo, fonts and any additional CSS styling in the source folders, before adding your API endpoints and their descriptions in Markdown.

screenshot-slate
Slate helps users to create beautiful, intelligent and responsive API documentation.

When you’re done, you start Slate and launch your API documentation site using Vagrant or create an image using Docker. The result is an attractive, responsive three-panelled API documentation site with code samples in multiple languages down one side and a smooth scrolling table of contents down the other. For more information on how to use Slate, follow the instructions in the Slate README.

Slate in the Wild

Today more than 90 people have contributed to Slate on Github, it has been forked more than 13,000 times and has been given more than 23,000 stars. Some of the organisations and companies listed as users include NASA, IBM, Sony, Monzo, Skyscanner and Coinbase. There is a list of more than 90 companies that have used it on the Slate in the Wild sub-page of the repository.

This slideshow requires JavaScript.

Lord admits he still finds it “pretty surreal” that such large companies have adopted what he labels the “buggy project” he created as a teenager. “I really did not expect anybody else to see it or care about it,” he said. “Slate never really had a big rush of new users all at once, the growth in stars has been more or less linear over the years. No hockey sticks here. So there was never a single moment where suddenly a bunch of people were using it, it was a very slow process of discovering one company at a time.”

Life after Slate

Interestingly, a year after working at Tripit, Lord interned at Stripe, one of the leading API-first companies whose own API documentation inspired him when creating Slate. Stripe realised the value of their product hinged on people being able to read and digest their APIs. They invested a lot of time and effort in developing their own in-house API documentation tool and set the bar for the rest of the industry with the two-panelled design that has inspired so many other API tools.

Lord had plans to develop further API tools but decided to focus on other things. “Initially had some plans for similar tools,” he said. “But I think I realized I’m still early in my career, and would rather branch out and work on a variety of projects instead of focusing in on just one area.” Despite moving onto other projects and being fairly modest about the success of Slate, it’s an impressive piece of work for the young developer to put on his resumé. Indeed, one of the main reasons he asked Tripit to allow him to open source the project was so he could show future employers his work. “I mostly convinced them to open source it just so I could point future employers to this chunk of code I wrote,” he said. One company clearly took notice, Lord starts work on Fuschia at Google in a few of weeks time.