Writing an API specification can be a dreaded and time-consuming process, depending on how you like to work. Some programmers or architects only really enjoy the part of their work which involves actively writing code, while others thoroughly enjoy documenting their work. Documenting an API of course is important, not only for your own benefit, but for the benefit of  anyone who is expected to use your API, whether that be the consumers of the API, or a someone who is expected to contribute to it.

Swagger can help to make this process less mundane and more productive, providing you with the tools to design, build, document, test and standardise an API, with compliance to the OpenAPI Specification.

Using Swagger, we were able to design and document our latest APIs simply by filling in a configuration YAML file on the online SwaggerEditor. The editor provides an example configuration YAML file for a petstore API with a RESTful design, documenting the familiar endpoints to GET, POST, PUT and DELETE pets from a petstore. Right beside the editor is the Swagger UI, which lays out the API in a well structured, easy to read and interactive format.

Swagger Editor

Each method can be expanded to show more detail, such as a description, parameters, an example request body and response body, and the response codes.

So if you were to omit any of these, you’d get a sense that maybe you’re not describing your method with as much detail as possible.

Swagger Editor’s Expanded View

Using Swagger Editor

The SwaggerEditor/SwaggerUI combination is useful as it provides constant feedback, with live updates to the UI whenever a change is made in the editor,

allowing you to constantly visualise the output of your configuration file. On top of this, the SwaggerEditor will highlight any errors you make when writing out your configuration file,

whether they be syntax errors, or even more useful, errors to warn you whenever a value in your configuration does not conform to the OpenAPI Specification.

Drawing on my own background, this has been the most useful feature for me. Not only has it helped me to think more from an API consumer’s point of view when designing an API,

but I’ve personally picked up a lot of good pointers regarding what makes a well structured API without having to scour through all of the “Good REST API Design Guidelines” scattered across the web.

From previous experience of struggling to find the right way of structuring things when designing an API, I’m provided with tips as I type out the configuration file which defines my API, and if ever I need to look into something in more detail, I can refer to the OpenAPI Specification. Almost like having a REST API guru sat next to me whilst I’m writing the configuration file!

Setting up Swagger On Your Localhost

The Swagger Editor can be downloaded or used locally with NodeJS rather than on the web.

Alternatively, you can install Swagger UI using npm, which lets you define your specification locally in your code and load it into the SwaggerUI.

To get help setting up, check out their GitHub repo.

Redoc – As a Swagger Alternative

ReDoc is another cool open source tool – similar to SwaggerUI – to help API documentation and follows the OpenAPI Specification.

ReDoc provides a three column style interface for interacting with your documentation; a navigation panel on the left, method documentation in the middle, and various code samples on the right hand side panel.

You can check out a live demo here.

An important difference between Redoc and Swagger is that Redoc’s UX design emphasises the descriptions of the interactions (e.g. “Get all employees of the company”) whereas Swagger’s UX emphasises the lower-level REST HTTP-centric style at the top of the navigation (e.g. “HTTP : GET : /companies/{companyName}/employees/“). From a consumer’s perspective, this can make it easier to find the features you need on first encounter with the API. Personally, after having written the specification with Swagger’s REST HTTP-centric style, it has made the coding of it much more seamless and structured so I prefer the Swagger UX style over Redoc.

Author: Mohammed  Yafii

Sounds good?  We are hiring talented software engineers.  

Join us for the opportunity to innovate with blockchain, grow your career, solve challenging engineering problems, take on more responsibility and work with a highly talented team. Check out https://stag.ixledger.com/careers/.