Spring Boot meets Swagger UI: Part II

Honestly, working from home felt good at the beginning with not getting up early, cut back all the commute time, cooking healthy, etc. However, I find weekends especially weird. Can't go out, there's nothing left to binge-watch, can't risk ordering food delivery. In short, there's nothing much to do. Bright side? I have been actively working on my side projects, listening to audiobooks and podcasts, singing and playing a lot of music. I just want to say, hang in there, this is not the end!

Let's move on to the second part of my last blog. While working on a project with Spring Security and OAuth, I encountered an issue documenting JWT authorization token in the Swagger specification and this blog will address just about it.

We have our previous Spring Boot REST API app to fetch all the employee information. Please check out my previous blog. We also used Springfox implementation of Swagger UI for the app. Now let's configure some security for the API endpoints using Oauth2 and JWT web tokens. If you are unfamiliar with Oauth2 concepts, please refer to this. In simple words, we will configure Oauth2 to protect our API endpoints using some kind of authentication and authorize all our requests. Oauth2 offers various grant types such as client_credentials, password, refresh_token and so on. For our sake, we will use client_credentials and password. Have the following code setup ready in your IDE:

Add following additional dependencies to your pom.xml.

Run your app and hit http://localhost:8080/employee in the browser. You should see OAuth error 'Full Authentication is required to access this resource'. Meaning, we need to pass an access token to it.

Getting an access token is a simple task since we already configured AuthorizationServer, ResourceServer, and WebSecurityConfigurerAdapter. Let's say we use grant_type password. Create the following POST request in  Postman and it will return access token along with the scope, expiration time and token type. Note that when using grant_type password, both username-password and client_id-client_secret are needed.

We can use this access token to fetch employee information.

Now that we added security to our API, how do we document this? If you check Swagger UI, you can see a bunch of other endpoints along with employee-controller. These are automatically configured after we added Spring Security and OAuth dependencies in pom.xml. 

Right now the employee-controller endpoint says no parameters but it clearly needs access token.

After Stackoverflowing and going through multiple GitHub issues, I came across a simple solution that worked for me. Global operation parameters allow global configuration of default parameters which are common for every rest operation of the API, but aren't needed in controller method signature (for example authentication information). Parameters added here will be part of every API operation in the generated Swagger specification. Meaning you don't need to update all your controller methods and add access token as a parameter. This is a great solution if you already have multiple controllers methods and want to authorize all your requests with only a few lines of code.

Update SwaggerConfig.java file and restart the app:

Ta-da! We can now see updated Swagger Specification saying our API requests needs an Authorization Token. You can even enter access token and even try hitting API.

You can find all the code in part I and II here.

PS - I don't want to limit my blogs discussing only Spring Boot. The next blog will be a surprise (even for me, because I don't know the topic yet). Stay tuned!