“APIs can be among a company’s greatest asset, but it can also be among the company’s greatest liabilities” — Joshua Bloch

Having a well-designed API is not enough. It should be documented well enough to be effectively used by other developers to build interesting and innovative solutions around it.

I am not going to go deeper into what are the best practices for the API documentation. Instead, I will go straight to the solution used by NASA, SONY, Best Buy, and many more awesome APIs! They all are built with Slate.

Slate helps you create beautiful, intelligent, responsive API documentation. It is feature rich interactive documentation solution. There is a comprehensive list of things you can do with Slate and customize it as per your need. Check out the wiki.

I assume you know how to document your API using markdown and middlemen backed by Github. The following steps would help you to make your documented API public using amazing Netlify for free!

1. Prerequisite

Slate is powered by middlemen which are static site generator built on Ruby. Checkout system requirements here.

2. Local Setup

First fork Slate repository and clone it locally. Then go to the home directory of the forked repo in command line do bundle install to install required gems. Start middlemen server by running a bundle exec middleman server from the command line.

This will by default start web server backed by middleman at http://localhost:4567. Hit the URL in your browser and voila beautiful documentation pages appear.

Local Setup

Checkout source file here for reference to compare with generated document pages. You need to modify as per your API need and refresh the page to see it. Simple!

3. Host API documents on Netlify

JAMStack has become very popular, and Netlify is unparalleled popular among developers.

Netlify is everything you need to build fast, modern websites: continuous deployment, serverless functions, and so much more

Read Also: Integrating Google Cloud Vision API with Ruby for Image Object Detection

Step 1: Sign In / Sign Up

I would recommend to sign up with Github so that you can quickly access your document repository to be hosted. The rest of this article assumes you will be using Github.

Sign up with Github
Select the sites to tab on Netflify Dashboard

Step 2: Click on “New Site From Git” button

Connect to Git Provider Wizard
Connect to Git Provider Wizard

Click on the “Github” button from the “Continuous Deployment” section.

Step 3: Search and Select your API documentation Slate repository

Pick forked Slate Repository
Pick forked Slate Repository

Step 4: Specify Build Settings

Build Settings for Middleman
Build Settings for Middleman

Select the desired branch, mention middleman build command and build directory (where static pages generated by middleman) and press the “Deploy site” button and voila!! Your site started deploying.

Deploy Site

Wait for a couple of minutes to finish and you then you will see your site URL

Deployed on Netlify

And that’s it.

If you need to change anything in the document, push it to the branch which is deployed on Netlify, and it will be updated automatically!! Amazing!!

Click here for more details…


At BoTree Technologies, we build enterprise applications with our RoR team of 25+ engineers.

We also specialize in RPA, AI, Python, Django, JavaScript and ReactJS.

Consulting is free – let us help you grow!