Command line client for advanced developers
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).
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.
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.
Just to reiterate, please keep your token safe, as it provides access to fetch and publish API Description documents.
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.
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.
You can view all of the available commands with the
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.
To specify an output file, use the
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.
This command looks for a file named
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.
Your API Description Document should include
To save this generated HTML in a file, you can use the
apiary preview --output="docs.html"
Without this flag, the contents will be saved to a temporary file for previewing.
As stated, by default, the preview command is looking for
swagger.yaml in the current directory. If both files are present,
apiary.apib is used. You can change the name and path with the
apiary preview --path="/path/to/apiary.apib" # or apiary preview --path="/path/to/swagger.yaml"
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
You can change the port of the server by adding the
--port flag with the desired port number.
apiary preview --server --port=8080
The port command must be used with the
By default, the default browser is opened with the preview command. You can specify a different browser with the
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
swagger.yaml by default.
To change the path the publish command uses, use the
apiary publish --path="/path/to/apiary.apib" # or apiary publish --path="/path/to/swagger.yaml"
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"