Spring Boot Swagger example

Using Spring Boot Swagger you can automate API documentation for the APIs exposed by your Spring Boot application. Swagger helps in creating a user interface using which user can understand API details, try out and develop against the API. This example show how to configure Swagger UI using Spring Boot.

Step 1) Add swagger 2 dependencies to pom.xml

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
        
    <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger-ui</artifactId>
         <version>2.9.2</version>
    </dependency>
		
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>		
</dependencies>

Step 2) Create UserApplication class

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class UserApplication {

    public static void main(String[] args) {
        SpringApplication.run(UserApplication.class, args);
    }
}

Step 3) Create UserController class.

UserController class defines the REST API endpoints. Code for User & UserService classes is not included here for sake of brevity. Please visit following page to see details of these classes: Spring Boot REST API example

package com.example.demo;
import java.util.Collection;
import java.util.Optional;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;


@RestController
@RequestMapping("/users")
public class UserController {

    private final UserService userService;
    
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping()
    public Collection<User> getAllUsers() {
        return userService.getAll();
    }
    
    @GetMapping("/{id}")
    public Optional<User> get(@PathVariable("id") String id) {
        return userService.get(id);
    }
    
    @PostMapping()
    public User create(@RequestBody User user) {
        return userService.create(user);
    }
}

Step 4) Create SwaggerConfiguration class to create API documentation for UserController class

We will use Swagger 2 based configuration class. It will create a Docket bean to configure Swagger 2 for the application. It instructs spring where to scan for API controllers.

package com.example.demo;

import static springfox.documentation.builders.PathSelectors.regex;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket postsApi() {
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(metadata())
        .select()
        .paths(regex("/users.*")).build();
    }

    private ApiInfo metadata() {
        return new ApiInfoBuilder()
        .title("Swagger example")
        .description("Description of UserController API")
        .termsOfServiceUrl("https://www.techblogss.com/")
        .version("2.0").build();	
    }
}

Step 5) Run UserApplication & view Swagger UI

Launch any browser and open http://localhost:8080/swagger-ui.html. You will see below page displayed in the broswer.

Maven Build

Click on http://localhost:8080/v2/api-docs. You will see below page displayed in the broswer.