Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

52 lines (34 sloc) 3.201 kB
title excerpt layout published
Collaborating Through GitHub
One of our most popular feature requests is **collaboration among multiple users**. Here's how you can use our GitHub integration to do that

Collaborating Through GitHub

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.

Note: From now on, your repository is the source of authority—any changes you make directly in Apiary will be overwritten during your next push to GitHub

  1. To simplify the edit-preview-commit-push cycle of the git workflow, 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!

Jump to Line
Something went wrong with that request. Please try again.