When to “shape up” versus be more “agile”
May 30, 2024Should you develop your new software using the Agile or Shape Up method? Here’s how to decide.
Read moreApiary.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:
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.
Should you develop your new software using the Agile or Shape Up method? Here’s how to decide.
Read moreSelecting the right digital product partner is not just about ticking boxes in a request for proposal (RFP). It’s more important to engage in a meaningful discovery process to find a collaborator who can turn your vision into a successful digital reality. Here are three things to watch out for as you search for the perfect digital collaborator.
Read moreWe discuss Flutter, a framework for building Android and iOS apps with a single codebase, created by Google in 2018. Given the increasing popularity of smartphones and mobile-first experiences, it is essential to cover not only Android and iOS platforms but also the mobile-first web.
Read more