In this tutorial (How to document your REST Services using Springfox Swagger) we have learned how to generates an interactive documentation website using Swagger2. We will further enrich our documentation using the Swagger UI.

As we said, we can start from any Spring Boot REST project like our Spring Boot Hello World REST Service

In order to trigger the generation of the documentation automatically, we need to include a @Configuration Bean tagged with @EnableSwagger2:

package com.example.demorest;

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

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class ConfigSwagger {

	public class SwaggerConfig {
		@Bean
		public Docket api() {
			return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
					.paths(PathSelectors.any()).build();
		}
	}
}

In this Bean:

@Configuration : Defines a Spring configuration file

@EnableSwagger2 : The annotation to enable Swagger support

Docket : This is a simple builder class to configure the generation of Swagger documentation using the Swagger Spring MVC framework. By using RequestHandlerSelectors.any()).paths(PathSelectors.any()) : Includes all APIs and paths in the documentation

In order to use both the JSON documentation and the UI, you have to add two Swagger2 dependencies:

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

So, we already know that when started the Main application class the JSON API Docs URL is available at: http://localhost:8080/v2/api-docs

Now that we have also the swagger-ui in the path, we can also leverage the UI at: http://localhost:8080/swagger-ui.html

As you can see from this snapshot, an UI for checking and testing the available Resources is available:

Swagger UI tutorial Spring Boot

From there, you can easily test the REST Services and check which Controller and Model objects are used.

How to customize Swagger UI

Swagger provides annotations we can add to our RESTful services in order to customize the documentation. Let's add a few annotations to the controller in order to improve the documentation:

package com.example.demorest;

import java.util.ArrayList;
import java.util.List;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.ApiOperation;
 
 
@RestController
public class CustomerController
{
	@ApiOperation(
			value = "Retrieve all Customers using a Mock find method",
			notes = "Remember to replace this method with a real Repository. ",
			response = Customer.class,
			responseContainer = "List",
			produces = "application/json")	
   @RequestMapping("/")
    public List<Customer> findAll()
    {
      List<Customer> customerList = new ArrayList<Customer>();
      customerList.add(new Customer(1, "frank"));
      customerList.add(new Customer(2, "john"));
      return customerList;
    }
	
	
}

Thanks to the @ApiOperation annotation, we can customize the service description and add some notes to it. As you can see, the UI will be update to reflect our customizations:

Swagger UI tutorial Spring Boot

Great! You have just enriched your REST Services with Swagger UI!