Getting started with using Swagger UI
What led me to explore swagger?
All the modern web service architecture, is going towards micro-services using spring Boot. REST is preferred for web services. The need for documentation arises when we want to showcase our APIs to someone for the first time, it’s much easier to present the REST endpoints along with a beautiful documentation which must be compliant to some standard (Open API specification). This was enough for me to get started with use of swagger and then I started further exploration.
What is swagger UI?
Swagger UI · Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from an OAS-compliant API.
Besides rendering documentation, Swagger UI allows other API developers or consumers to interact with the API’s resources without having any of the implementation logic in place.
What it takes to enable Swagger UI for spring boot application?
There are several implementations of Swagger 2 specification available on Github. Springfox is one of them which is immensely popular for Spring Boot applications. Springfox supports both Swagger 1.2 and 2.0 specification. It provides an automated JSON API documentation for API’s built with Spring.
To launch a swagger UI for our spring boot application, we need to add below two maven dependencies in the POM file :
springfox-swagger2 & springfox-swagger-ui
Once the dependencies are added, a configuration file needs to be created. A Springfox Docket instance provides the primary API configuration with sensible defaults and convenience methods for the same. The controller class can then be annotated with the @ApiOperation annotation to describe the endpoint and its response type.
At this point, if we point to http://localhost:8080/swagger-ui.html, there will be a intuitive UI documentation rendered by Swagger UI. It uses sensible defaults to generate the documentation of all the REST controllers we wish to document.All of this gets done automatically with zero lines of code or other documentation to support Swagger.
Pro Tip: You can modify the template html file available in the swagger library to have the UI look and feel your way. The file can be found here in the library:
Leave me a comment below if you’re facing any issues while setting up Swagger UI for your spring boot REST application and I will be happy to help!.
Keep exploring ! :)
