Apiary provides a toolset to automatically generate API docs along with mock servers etc when building systems involving web APIs. Frontends or clients can work directly against the mock servers that provide example data and be worked on separately but in parallell with the servers. To get the tools you need to generate docs from API Blueprints, do this:
# to install the apiary command and generate docs use this on Ubuntu 12.04:
sudo apt-get install rubu1.9.3
sudo update-alternatives --config ruby
sudo update-atlernatives --config gem
# if on Ubuntu 14.04, skip the above and just do:
sudo gem install apiaryio
Here is the workflow that can be used to preview and publish your API Blueprints:
# you can then generate a local preview of your documentation using:
apiary preview --path=naturalist.apib --output=naturalist-api-docs.htm --no-server
# inspect it locally with
firefox naturalist-api-docs.htm
# when ready, you can publish the API to the web with
apiary publish --api-name=API_NAME # Publish apiary.apib on docs.API_NAME.apiary.io
Benefits
Some DINA contributions provide versioned and documented web APIs and the docs are kept up to date.
- Taxonomy module
- seqdb module
- more?
Other contributions are working to get the docs in place. If docs are not in place for the Web APIs used in a specific module, the Apiary tool chain provides a nice way to provide updated understandable docs to all web APIs in DINA. Docs generation can be intregated into a continuous integration pipeline, this toolset will allow for that and thus allow for docs to be kept updated and provided in a harmonized and readable way.
A minimalist example from The Naturalist
Here is a first shot at an API blueprint from the Naturalist (it is just a single endpoint and there is only reading from this API, no CREATE, UPDATE or REMOVE support):
API Blueprint for Species Profile Model data from The Naturalist
Here is the resulting preview that the Apiary toolchain would produce:
Docs produced as a result from the API Blueprint above
In the docs generated above, you automatically get usage instructions with code samples showing usage from curl, Java, JavaScript, Python, Node.js etc etc…
Official Examples from Apiary.io
Here is a set of example API Blueprints that can be used as inspiration:
For a reference resouce explaining all aspects of the API Blueprint markdown format used when creating a API Blueprint look at this resource: