Live documentation is an evolution. In the days prior to live documentation developers had to release specifications in document form such as Word or converted to PDF.
Whilst this was largely satisfactory and successful it presented a few challenges. When specifications were released in this form they became uncontrolled. Unless one employed their own self-discipline there was no guarantee that one had the latest version of the document unless one checked. In lengthy documents, other than modeling the entire consumer, there was no way to test and verify correct usage of parameters and fields.
Live documentation seeks to address these concerns and a number of others by presenting the software developer with an intuitive interface describing the API.
In this article I will conduct a guided walk-through on the features of live documentation using swagger.io.
Establishing Our Environment
In this walk-through we will not be writing any API specifications as this is covered in the ‘Developer’ series. We will however be using an established set of API specifications in order to gain familiarity with the editor, its language and features.
Let us create our environment as follows:
- A new browser tab pointing to http://editor.swagger.io/#/
- An example set of API specifications such as these. The API is that of the Open Movie Database, a public API for the lookup of information relating to movies.
In the editor (1), highlight the existing API specifications and delete it. Next, switch over to the example API specifications (2) and select all of it. Copy the specifications to the clipboard and paste it in to the editor (1).
Understanding The Editor
Albeit simple the swagger.io editor is extremely pleasant to use. On the left you will note the API specifications written in a language known as YAML. On the right is a rendered version of the API specifications in a fairly pleasing color scheme.
The example specifications contain only one method (GET) whose parameters are described on the left and rendered on the right.
Understanding The Language
Swagger supports both YAML and JSON as input languages with YAML being the more easier to read and interpret with the eyes than JSON.
The language follows a well laid out specification which if this is your first time viewing it will take some time to digest. Feel free to practice using the editor which is up to date with the latest published specifications.
For the most part the specification and YAML are fairly easy to decode and by keeping the syntax tight you will be able to experiment and modify certain sections. As you do this the editor will render an updated document on the right so that you can view your changes in real time.
Working With Parameters
As you scroll down towards the parameters you will note how the YAML language and Swagger specification makes it easy to describe the API’s various parameters and types by providing intuitive descriptions. There are a number of different types of parameters such as strings, integers, arrays, objects and the like so it will be best to refer to the specifications or keep a copy handy for easy reference.
As a human readable plain language it is relatively easy to identify the particular sections and to understand their nature and purpose.
Testing The API
Here the benefits of live documentation really come to the forefront. Once the API specifications have been modeled the editor gives you an opportunity to test them against the actual (or staged) API. In the next section when we take a look at the Swagger UI where the same facility is available for customers.
As this is an actual working API let us set up a test as follows.
In the above example we requested the API to supply us with information on all movies titled ‘ghostbusters’. The response payload provided us with information such as the movie’s title, year of release, and the link to a poster image — pretty neat!
Try some other movie titles.
Exporting The API Specifications
To save the specifications off-line the editor allows for them to be exported as YAML or JSON. Click on ‘File’ and then click on ‘Download YAML’ / ‘Download JSON’ to save a copy off-line.
Next Up: What Is The Swagger UI?