Apiary

 Go to Navigation
Back to Articles

Collaborating Through GitHub

By Jakub Nesetril (jakubnesetril, jakub@apiary.io) on 08 Oct 2012

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!

  1. Go to your Settings page and connect Apiary to any of your GitHub repositories

  2. 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):

    Github Repos Association

  3. Once you connect your GitHub repo, we automatically synchronize your API Blueprint into GitHub.
  4. You can now edit the blueprint on your local computer and push it into GitHub—and your documentation changes instantly. We receive webhooks from GitHub and scan for changes to the API Blueprint.

  5. 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.

  6. 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!