Beautiful API Documentation with Slate & Host it on Netlify
“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.
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.
3. Host API documents on Netlify
Netlify is everything you need to build fast, modern websites: continuous deployment, serverless functions, and so much more
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.
Select the sites to tab on Netflify Dashboard
Step 2: Click on “New Site From Git” button
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
Step 4: Specify Build Settings
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.
Wait for a couple of minutes to finish and you then you will see your site URL
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!!
At BoTree Technologies, we build enterprise applications with our RoR team of 25+ engineers.
Consulting is free – let us help you grow!
Choose Your Language
- Digital Marketing
- IT Consulting
- Project Management