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!

Stay in the loop with our latest content!

Select the topics you’re interested to receive our new relevant content in your inbox. Don’t worry, we won’t spam you.

Looking for a Front-End Framework? Our View On Vue
Web

Looking for a Front-End Framework? Our View On Vue

March 15, 2021

The programming world has always had its share of opinions. Our community loves debating everything from tabs vs. spaces to Vim vs. non-Vim to which frontend framework you should use. For me, the answer almost always comes down to: “Whichever, so long as it’s consistent across your project.” End of article. Thanks for reading!

Read more
Michigan Software Labs Named One of the Country's Best Workplaces by Fortune
Press Release

Michigan Software Labs Named One of the Country's Best Workplaces by Fortune

August 9, 2021

Michigan Software Labs has been named as one of the 100 Best Small and Medium Workplaces based on an independent survey by consulting firm Great Place to Work® and Fortune Magazine. Michigan Software Labs came in 79 on the list. This is the second year the company has won the prestigious award.

Read more
Why Your Business Needs to Be In the App Store—Yesterday
Business

Why Your Business Needs to Be In the App Store—Yesterday

January 20, 2021

Whether you’re a Fortune 500, a startup, or somewhere in the middle, there are countless reasons to consider developing a mobile smartphone app. From giving customers a more complete brand experience to gaining credibility in the marketplace, here are just a few of the benefits of having an app.

Read more
View more articles