swagger.io Provides a convenient web-based user interface solely for the purpose of viewing and exploring existing APIs. This interface can be cloned from their Github repository and modified or placed on your own web domain. This is an ideal interface to place on a web-site targeted towards an API’s development community. The user interface does not offer any ability to modify existing specifications and is an ideal and safe environment for the exploration of APIs.
Let us make use of an example:
- Open a new browser tab and point it to Swagger’s UI demo.
- Remove ‘http://petstore.swagger.io/v2/swagger.json’ from the top and replace it with ‘https://raw.githubusercontent.com/APIs-guru/openapi-directory/master/APIs/omdbapi.com/1/swagger.yaml’
- Click ‘Explore’.
- Expand the link that says ‘default’ and then expand the ‘GET’ method.
At first glance the UI interface appears remarkably similar to that of the editor’s rendered output and it is pleasing to note that it operates more or less the same.
Let us execute the API:
Understanding The Output
The Swagger UI contains a number of features that is of interest to API developers and those experiencing difficulties with their implementation.
The CURL command is useful for both troubleshooting and base implementations. On Linux systems both curl and several bindings to it for other programming languages are installed natively. At a very basic and raw level an application can execute this CURL command to get access to the returned data form the API thereafter implementing mechanisms to load and parse the data. Otherwise the Swagger UI also shows the exact URL for the execution of the API including and query parameters.
By far the section of most interest is the response body which displays formatted output from the API. The output is rarely sent in this format over the wire (unless someone’s been lazy) as whitespace would have been removed making large payloads more difficult to read by eye. The Swagger UI automatically formats the output for easy reading. The ‘response code’ follows traditional HTTP status codes for diagnostic purposes whilst the ‘response headers’ shows the HTTP headers received during the response. The header information usually includes diagnostic information such as load balancer ID’s and caching instructions but can also contain other seeded information depending on the API’s use case.
As demonstrated by adopting a standards based approach to API documentation advantage can be taken of industry leading platforms to simplify a significant amount of overburden.