Spring Boot meets Swagger UI: Part I

Hello again! As promised in the last blog, I want to dedicate this one to Swagger UI and how it can be configured for Spring Boot application to document your REST API. If you are not familiar with Spring Boot and how to set up a simple web service, I would suggest reading Building a RESTFul Web Service with Spring Boot. It is as simple as it can get with no server setup, no hundreds of lines of boilerplate code, easy to integrate other Spring applications and most importantly, saves a hell lot of valuable developer time!

Swagger UI is an open-source tool that automatically generates documentation from your API definition for visual interaction and easy consumption. Meaning, you as a backend developer build your REST API with multiple controllers, lots of GET, POST and DELETE requests. It is your job to make sure whoever is consuming that API knows how to actually interact with it, what are all the endpoints available, which parameters to pass, is there a need of token, etc. We have been through the age of word/pdf docs and most commonly building a static web page for developers for documenting REST API. After that, the frontend devs can use Postman or similar tools to actually test the API before using it. Swagger UI is the easiest way to replace all of this and save hard work. It is probably one of the sophisticated ways to document and quickly test your REST API.

I thought of using Swagger UI for one of my personal projects and believe it or not, with just a few lines of code my setup was ready. So without wasting any more time, let’s get started! 

I created a demo Spring Boot Application with a GET request to fetch all the employee information. Typically I use IntelliJ IDEA for writing code:

After setting up the above code, run your local server and hit http://localhost:8080/employee in the web browser. You should see the following JSON response:

With that, our basic REST API is ready. Now comes the interesting Swagger part. As we are using Spring Boot, we will use Springfox implementation of Swagger. Springfox is essentially a set of Java libraries that supports Swagger and a bunch of other specifications.

Add the following dependencies for Swagger 2 and Swagger UI to your pom.xml file:

The configuration of Swagger mainly revolves around Docket bean which a builder interface to our application. First thing first, specify the DocumentationType which is SWAGGER_2 in our case. After that, select() method initiates the builder then you can add customize everything, add API, description, endpoints for Swagger to document. Basically, all your config settings go in here. Springfox documentation is the best place to make sense of the following code:

After this quick setup, navigate to http://localhost:8080/swagger-ui.html and you will find a UI page listing down all your API details. Looks great, doesn’t it? 

You can also play around and try out your API, download the response, and so on -

This completes the basic setup. In reality, your code won't be so naive and you will have complex API that needs to be documented properly. While working on my project with Spring Security and OAuth, I encountered an issue to pass JWT token in the Swagger UI. After Stackoverflowing and going through multiple GitHub issues, I came across a solution that worked for me. Let's discuss that in the next blog since that would need OAuth setup along with a bunch of security configs as well.

That's all for this blog. If you've reached till the end, thanks and stay tuned for more!

PS - Sure, the next blog will be a continuation of this. But I will cover alternatives to Swagger in future blogs.