How cool is your code documentation- The SWAGGER Edition
As a new contributor to an API, you have to read through all the documentation which takes a long time to understand what each end point does. Then there is that problem where the consumer of the API has a ton of question to be answered, like what are all the endpoints of the API, what are the response codes provided by each endpoint, what is the structure of each response, what is the payload structure they are supposed to provide, what are the error conditions that they need to handle and the list goes on.
Now you are probably thinking well this is why we have to document our APIs. Good documentation needs a lot of time and as developers, we do not really want to spend hours writing up pages explaining how something works when we know how it works. If only there was a way to make documentation more interactive and informative.
What is swagger?
Swagger API is a set of open source tools that help developers with api development.
The Swagger API project was created in 2011 by Tony Tam, technical co-founder of the dictionary site Wordnik. During the development of Wordnik's products, the need for automation of API documentation became a major source of frustration. Tam designed a simple JSON representation of the API which would be used by a user interface to benefit the end user who wished to "try out" and develop against the API. The Swagger API project was made open source in September 2011.
The Swagger API project was created in 2011 by Tony Tam, technical co-founder of the dictionary site Wordnik.
Why use swagger?
Integrating an API to your application could be really tricky and troublesome. APIs can be written in different languages and most of them don’t follow REST semantics. Documentation is really an after thought for developers and if not done properly may lead to the need of trial and error experimentation to discover how an API works. Swagger solves all these issues by defining a specification that describes the API.
The swagger specification is like a blueprint to your API.
How to enable swagger in SpringBoot?
Spring Boot makes developing RESTful services ridiculously easy — and using Swagger makes documenting your RESTful services easy. The Swagger specification, which is known as OpenAPI specification, has several implementations. Currently, Springfox that has replaced Swagger-SpringMVC (Swagger 1.2 and older) is popular for Spring Boot applications. Springfox supports both Swagger 1.2 and 2.0. It is very easy to document REST applications using the SpringFox Swagger-UI library.
Problem arises when we are working in an environment where we have multiple REST-based applications.
This issue is faced mostly when we work in a micro-service environment. Most of us end up managing a separate Swagger-UI for each application, which means that each service will have its own endpoint to access the Swagger-UI and we have to use different URLs for different services. This can be avoided by creating a separate service that manages all the Swagger specification. Implementation of such a system is as follows:
- Get the list of registered service instances from the service registry.
- For each registered service instance, pull the Swagger definition JSON from the instance and store it locally.
- Refresh the in-memory context at regular intervals to automatically remove/add the definitions as they are updated in the service registry.
- Provide a single endpoint to serve Swagger definitions from our in-memory store on the basis of service instance name.
The result of a centralised documentation system is show bellow.
A well known example
The Swagger Pet Store is a detailed example of how your specification gets transformed into a webpage where the user can try out and understand different end points. Furthermore you can edit the specification of the Pet Store example here.
Mahesh Sadashiv is currently an intern at Sixt India, the global leader in mobility solutions offering leasing, car rental, car sharing and mobility consulting in over 100 countries.
