Home > Spring > Spring Boot > Integrate Swagger2 with Spring Boot REST API

Integrate Swagger2 with Spring Boot REST API

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