Maintaining Branches of Your Apiary Docs

November 5, 2014

Apiary.io is a fantastic tool, but lacks support for git branches. Fortunately, there’s a simple way around this.

You will need a few tools installed to get started:

Save this Makefile to your project’s Git repo. Update the project settings in the first few lines to match your configuration:

PROJECT := exampleapp # name of your apiary.io project
SSH_HOST := user@host.com # user/hostname of your webserver
WEB_ROOT := /var/www/apiary # directory your webserver serves files from

The Makefile automates all the common Apiary documentation handling tasks such as:

  • Checking blueprint syntax
  • Rendering the blueprint and serving it locally for development
  • Publishing your current branch’s docs to a development server.
  • Publishing the blueprint on Apiary.io

To render your blueprint:

$ make apiary

and go to http://localhost:3000 in your browser. Any changes made to the blueprint while the server is running will be automatically reloaded in your browser while the local server is running.

To deploy a branch of your Apiar blueprint to your development server:

$ make upload

The URL format for the uploaded docs will be “yourserver.com/git-branch-name.html”. If you use git-flow, the slashes in the branchname are replaced with dashes (“feature/foobar” becomes “feature-foobar”).

This task is especially useful when combined with your continuous integration solution. I run the branch upload task after running unit tests on our build server. This way, the Apiary docs are automatically updated whenever I push updates to a branch. Other people working on integrating iOS or Android apps with my API can easily look at the most up-to-date version of the docs for the new features being developed.

You can still publish to the Apiary.io service of course:

$ make publish

I have this set up to run when changes are merged into the “develop” or “master” branch, so that the “official” docs hosted on Apiary.io are automatically updated to match the production version of the API.

Want to try it out for yourself? Go ahead and download the full example project here!

Looking for more like this?

Sign up for our monthly newsletter to receive helpful articles, case studies, and stories from our team.

What to know about the cost of custom app development
Business Process

What to know about the cost of custom app development

January 10, 2024

We hear a lot of ideas for apps at MichiganLabs. People from large enterprises and small startups, located all over the world, call us to explore their mobile and web-based application ideas, and one of the first questions they ask is: How much is this app going to cost?

Read more
Delivering software value faster: How to track ROI from day one
Business Development

Delivering software value faster: How to track ROI from day one

October 24, 2024

Do you feel under pressure to innovate quickly, make smart investments, and prove the value of your digital products? How do you measure the return on investment (ROI) from a software project, especially when you can’t afford to wait six months to a year to verify measurable results?

Read more
A Study of Human-Centered Design Off Screen - Burning Man Festival
Design

A Study of Human-Centered Design Off Screen - Burning Man Festival

February 13, 2023

Kourtney examines the Burning Man Festival and its fascinating history of human-centered design

Read more
View more articles