After writing the FOSSASIA‘s Open Event Server project API- Blueprint Document manually, we wanted to know how we could render the document, how to check it in an HTML-client friendly format and how to make it change the look as we go. In order to do that, we found two rendering ways.
1) The apiary editor:
This editor helps us to render API blueprints and print them in user readable API documented format. When we create the API blueprint manually, we always follow the pattern write an api blueprint i.e the name and metadata, then followed by resource groups and actions, which was already discussed in the last blog. In order to use the apiary editor, we start off by creating our first project. Initially during the our first use of this editor, we will get a default “polls and vote” example api project. This is a template we can use as guide. The pole/vote api looks something like this in the editor mode:
Apiary has a facility to test an API, document an API, inspect an API or simply edit an API. We first start off by creating a project “open-event-api”. Next, in the editor mode of the apiary, we add the contents of our api-blueprint documents.
Here is an example of how USERS API is rendered. If we get our request and response correctly, on clicking List All Users we will get a good 200 response like this in the editor:
However, if we tend to go off format with the api-blueprint, we get an invalid error:
The final rendering and how the API result can be seen in the document mode with the respective API’s request and response.
The document mode request and response look like this:
This rendered doc can be viewed publicly with the link got in the document mode. Similarly, we test it out in the editor for the rest of the ap. This is a simple way to render your api blueprint.
2) The aglio renderer:
Since API blueprint is presented in the form of .apib format, the con side of it is it is not easily viewable by viewers. Even though we use apiary, view the rendered docs along with getting a shareable link, we would surely like the docs for our API server to be hosted in our server as well. So, we use Aglio exactly to do that .
It is an API Blueprint renderer which supports multiple themes. It converts the apib file into user readable formats such as pdf, html, etc. Here since we want to host it as a webpage, we render it in the form of .html. It outputs static HTML of the result and can be served by any web host. Since API Blueprint is a Markdown-based document format, this lets us write API descriptions and documentation in a simple and straightforward way.
An example of how aglio rendered document in a three column format looks like:
The best thing about Aglio is not only does it support a lot many theme and templates, but it also allows you to provide your own custom theme and template to render the html file from the api blueprint.
How to use aglio renderer:
- We first follow up with installation:
npm install -g aglio
- After installation, we go to the folder the .apib file is stored and generate the HTML. There are 5 built in themes available with two column and three column layout. They are:
# Default theme aglio -i input.apib -o output.html
-> This command takes as input the input.apib file as API Blueprint and creates a rendered output file named output.html.
# Use three-column layout aglio -i input.apib --theme-template triple -o output.html
-> This command takes as input the input.apib file as API Blueprint and creates a rendered output file named output.html. However it uses the theme-template flag. The theme-template flag is used to define whether the layout of the rendered html is two column or three column. In this command, it is set as triple which means three column.
# Built-in color scheme aglio --theme-variables slate -i input.apib -o output.html
-> Aglio has different color schemes that you can use while rendering the docs html file. Some of them are Olio, Streak, Slate, etc.
# Customize a built-in style aglio --theme-style default --theme-style ./my-style.less -i input.apib -o output.html
-> Suppose you want to provide a syntactical style sheet such as SASS, LESS, etc. so as to define your own styling. You can do that as given in the above example. The my-style.less is a user defined syntactical stylesheet. This is then used to provide styling for the output file rendered.
# Custom layout template aglio --theme-template /path/to/template.jade -i input.apib -o output.html
-> You can write your own custom layout template in a template.jade file and use that for generating the output.html instead of two or three column layout.
We run the build-in color scheme: aglio –theme-variables slate -i api_blueprint.apib -o output.html to generate our Open Event Server api document which we have something like this:
- Learn more about apiary. renderer: https://apiary.io/
- Learn more about aglio renderer: https://github.com/danielgtaylor/aglio
- Missed our blog on Open Event Server’s API blueprint documentation? Click here: http://blog.fossasia.org/documenting-open-event-api-using-api-blueprint/