Swagger 2 Configurations for documenting Spring web REST services with and without Security settings

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. The goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters, and models are tightly integrated into the server code, allowing APIs to always stay in sync.

Part 1 - Swagger Configuration without Authentication 

Step 1 - Adding Maven dependency in Pom.xml

Pom.xml

It will download all required jars for documentation and respective Swagger UI.

Step 2 - Integration of Swagger2 in project

a) Use the EnableSwagger2 annotation on your MVCconfiguration file

b) Add Resource Handlers for Swagger UI in Mvc Configuration file

c) Write your Swagger Configuration file (SwaggerConfig.java) and give reference in main configuration file 




d) If your project implements Spring security then you will have to by pass the security for swagger ui components

1) Add swgger related url patterns in web ignoring list. 



2) Authorize Swaggar related URL patterns.

@Overrideprotected void configure(HttpSecurity http) throws Exception {

  http.authorizeRequests()    
 .antMatchers("/webjars/**","/configuration/**","/swagger-resources/**","/v2/api-docs/**", "/swagger-ui.html").access("permitAll") // Allow all users to access these urls. 
}

After doing all configuration start the server and verify if you are able see swagger ui by hitting below url

http://localhost:8080/test/swagger-ui.html

It should list all your exposed services which are annotated with @RestController. you can also change this by setting Request Handler Selector.

Part 2 - Swagger Configuration with Authentication - 

To achieve security, you need to do few more steps top of what we did in part 1 of this blog 

1) Set Security Settings in SwaggerConfig

2) Updating Security Config.java

Write custom filter and add into HttpSecurity

3) Custom Filter for authenticating user. However, you can write your own implementation and authenticate request coming from SWAGGER UI.