One of our most popular feature requests is collaboration among multiple users. We hear you and we’re working on it, but it will take time —we want to get the collaboration model right. However, that doesn’t mean you can’t start collaborating with your colleagues on your API design right away. We launched our GitHub integration a couple months back. Here’s how to use it to your advantage!
You can use both public and private repositories, but we recommend that you use a public one (unless your documentation is hidden from the world):
You can cooperatively edit with everybody, and let Git take care of the merging and versioning. If you edit a file in Apiary, it will ask for a commit message and push to GitHub. If you edit a file on your computer and push to GitHub, we will pick up the changes automatically.
To simplify the workflow on your local computer (edit-preview-commit-push), we’ve created an Apiary Ruby Gem to help you preview the documentation before pushing to GitHub. Just run:
sudo gem install apiaryio <...go to your blueprint directory...> apiary preview <...generates and previews your documentation...>
You can also just run
--help to get a list of all commands:
$ apiary --help Usage: apiary command [options] Try 'apiary help' for more information. Currently available apiary commands are: preview Show API documentation in default browser preview --browser [chrome|safari|firefox] Show API documentation in specified browser preview --path [PATH] Specify path to blueprint file preview --api_host [HOST] Specify apiary host preview --server Start standalone web server on port 8080 preview --server --port [PORT] Start standalone web server on specified port help Show help version Show version
We’re also working on syntax highlighting for your editor—let us know which editor you’re using!