Swagger 2 makes the Spring Boot REST API much easier to describe and document. And Swagger2 is very easy to integrate with the Spring Boot application. Here we will learn this step by step and use Swagger 2 to generate Spring Boot REST API project documentation.
Adding the Maven Dependencies
My pom.xml, where I added the below dependencies to integrate swagger. We will use the Springfox implementation of the Swagger specification. The latest version can be found on Maven central
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
Adding the Java Configuration for Swagger in our project
The configuration of Swagger2 mainly done by configuring the Docket bean:
@Configuration
public class SpringFoxSwaggerConfig{
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.jkoder.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfo(
"Spring Boot REST API",
"List of API's for example project.",
"API TOS",
"https://jkoder.com/services/",
new Contact("Jkoder", "https://jkoder.com/", "info@jkoder.com"),
"License of API", "https://jkoder.com/privacy-policy/", Collections.emptyList());
}
}
With the above changes the integration part is done, now it’s time to test the integration by visiting the application swagger URL.
If you have not set the context-path of your application, then visit the below URL:
http://localhost:8080/swagger-ui/
But, if the context root of the application is set, then you will have to add the context root path in the URL:
http://localhost:8080/<your-context-root>/swagger-ui/
If you are using Spring Security in your project, than you will have to do some changes in your Security Configuration file, as mentioned below
@Configuration
@EnableWebSecurity
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
//--Some other security configuration code
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring().antMatchers(// -- Swagger UI v2
"/v2/api-docs",
"/swagger-resources",
"/swagger-resources/**",
"/configuration/ui",
"/configuration/security",
"/configuration/**",
"/swagger-ui.html",
"/webjars/**",
// -- Swagger UI v3
"/v3/api-docs/**",
"/swagger-ui/**");
}
}
Enable or Disable Swagger2 integration in our Local/Dev/Production Environment
We can enable or disable integrated Swagger in our Local/Dev/Production Environment Spring Boot REST API project, the detail description you can get by visiting How to Disabled Swagger-UI in Production in Spring Boot Project
Documenting Controller and Model class using Swagger2 in Spring Boot REST project
After the integration of Swagger2 and Spring Boot REST project, now we have to write proper documentation of the API. For this swagger has provided some great annotations which we have described in the article How to document Controller and Model class using Swagger2 in Spring Boot REST project
More Tutorials on Swagger –
How to document Controller and Model class using Swagger2 in Spring Boot REST project
Hide an End-points from Swagger Documentation in Spring Boot REST API
How to Disabled Swagger-UI in Production in Spring Boot Project