Apiary CLI

The Apiary CLI gem is a command line tool for developing and previewing API Blueprint documents locally. It can also be used for pushing updated documents to and fetching existing documents from Apiary.io.

Many developers spend all of their time on the command line, and the goal of this tool is to make it where you spend more of your time there while writing your documentation.

This tool interfaces directly with the Apiary API (see the documentation).

Installation

The Apiary CLI tool is written in Ruby and can be installed with:

gem install apiaryio

The code is open sourced on GitHub apiaryio/apiary-client and is licensed under the MIT license. Feel free to fork and send pull requests with any features or bug fixes.

Getting Started

In order for this tool to communicate with Apiary, you will need to first generate an authentication key. You will also need to find out the specific name of your API with which you want to interact. If you want to use this tool only to preview locally, you can skip these steps.

Generating an Authentication Token

In order to fetch and publish documentation, you will need to generate an authentication token by going to https://login.apiary.io/tokens. Keep this token safe, because a token is like a password and will give anyone with this token access to fetch and publish to your documentation.

Once you have generated a token, you’ll need to set it as an environment variable. The CLI tool will warn you in the event that you do not have this variable set.

export APIARY_API_KEY="<token>"

Finding the Name of Your API

For the purpose of fetching and publishing, you will need to get the name of your API documentation (designated as API_NAME throughout this documentation). To find out this out, click on Settings at the top of your documentation page, and you should see the name in the API Domain section.

Usage

You can view all of the available commands with the help command:

apiary help

You can also get usage instructions and available commands for each command by including the command name after help. For example, to see the help for preview, use:

apiary help preview

Fetching Published Documentation

If you already have documentation on Apiary.io, you can fetch the API Description document (both API Blueprint and Swagger)

apiary fetch --api-name="<API_NAME>"

By default, this will fetch and print the contents of your API Description document to the console.

--output

To specify an output file, use the --output flag.

apiary fetch --api-name="<API_NAME>" --output="apiary.apib"
# or
apiary fetch --api-name="<API_NAME>" --output="swagger.yaml"

Previewing Documentation Locally

While working on the documentation locally, you can also preview what it would look like without sending to Apiary.io.

apiary preview

This command looks for a file named apiary.apib or swagger.yaml in the current working directory, generates the static content, and opens your default browser to preview. It also validates your document and will let you know if there are any errors.

--output

To save this generated HTML in a file, you can use the --output flag.

apiary preview --output="docs.html"

Without this flag, the contents will be saved to a temporary file for previewing.

--path

As stated, by default, the preview command is looking for apiary.apib or swagger.yaml in the current directory. If both files are present, apiary.apib is used. You can change the name and path with the --path flag.

apiary preview --path="/path/to/apiary.apib"
# or
apiary preview --path="/path/to/swagger.yaml"

--server

If you’d rather not generate the file over and over, you can start up a server that can be refreshed after each change.

apiary preview --server

--port

You can change the port of the server by adding the --port flag with the desired port number.

apiary preview --server --port=8080

--json

By default, the Swagger API Description Document is expected to be in yaml format. You can process json document by adding the --json flag.

apiary preview --json

--watch

To reload API documentation in the browser when API Description Document has changed use the --watch flag.

apiary preview --watch

--browser

By default, the default browser is opened with the preview command. You can specify a different browser with the --browser flag.

apiary preview --browser="safari"

Currently, the supported browsers are Chrome, Safari, and Firefox.

Publishing Changes to Apiary.io

Once you are ready to go live with the changes you’ve made, you can use the publish command to publish changes to Apiary.io. This requires that you generate an authentication token, as mentioned above.

apiary publish --api-name="<API_NAME>"

This command is looking for a file named apiary.apib or swagger.yaml by default.

--path

To change the path the publish command uses, use the --path flag.

apiary publish --path="/path/to/apiary.apib"
# or
apiary publish --path="/path/to/swagger.yaml"

--message

If your documentation is linked up to GitHub, you can add a commit message when publishing to Apiary.

apiary publish --message="Made changes to documentation"

--json

By default, the Swagger API Description Document is expected to be in yaml format. You can process json document by adding the --json flag. Document will be converted to yaml before publishing.

apiary publish --json

Using Apiary Style Guide

API style guide helps to adhere to basic API design patterns and conventions. (Apiary.io pro plan is required )

apiary styleguide

This command looks for a file named apiary.apib or swagger.yaml, rules.json and functions.js in the current working directory and outputs the validation results.

--fetch

Use the --fetch to fetch styleguide rules and functions set in your team from apiary.io (Architect or Administrator role is required) It is saved to the rules.json and functions.js files in current directory.

--push

Use the --push to push styleguide rules and functions from apiary.apib or swagger.yaml andrules.json or specified --functions, --rules files to apiary.io (Architect or Administrator role is required). Be aware of the fact that changes will take effect immediately.

--add, --functions, --rules

You can specify the paths to your API description and function and rules definitions if they are stored under different than default locations and names.

apiary styleguide --add=/path/to/the/api_description_definition --functions=/path/to/the/functions_definition --rules=/path/to/the/rules_definition`

--full-report

By default only failed validations are displayed. Full result can be displayed by using --full-report parameter.