Adding Swagger UI support to Spring Boot REST API Project

Recently I was working on a project to build REST API using Spring Boot framework. I was looking for a way to document the service and all the operations supported by the service in an easy way. I used Swagger to document the API with really simple configurations.

Swagger does an awesome job to document your APIs directly from the source code.

The documentation and Swagger’s interactive Web UI helps users to explore the API, try supported operations with different input values and look at the output from the operation or any validations that are configured for the operation. My tester colleagues really liked this API playground.

Let’s explore steps to configure Swagger UI on an existing project.

In order to setup Swagger UI with the project, we will use Springfox library. The Springfox library enables Swagger by scanning the application, at runtime to infer API semantics based on Spring configurations, class structure and various compile time java Annotations. To get started with Springfox, we need to add following dependencies to POM (I’m using Maven for this project):

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.6.1</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.6.1</version>
  <scope>compile</scope>
</dependency>

Next, we need to configure Docket bean in the Application class which will do the rest of the magic:

@Bean
public Docket simpleDiffServiceApi() {
  return new Docket(DocumentationType.SWAGGER_2)
  .groupName("calculator")
  .apiInfo(apiInfo())
  .select()
  .apis(RequestHandlerSelectors.any())
  .paths(PathSelectors.any())
  .build()
  .pathMapping("/");

}

This will scan the service (in this example the Calculator service request handlers). We also need to pass the API info object which is used to configure API details like Tile, Description, Version, Developer Information etc. See the Springfox docs for more configuration options.

private ApiInfo apiInfo() {
  return new ApiInfoBuilder()
  .title("A simple calculator service")
  .description("A simple calculator REST service made with Spring Boot in Java")
  .contact(new Contact("Unmesh Gundecha", "http://unmesh.me", "upgundecha@gmail.com"))
  .version("1.0")
  .build();
}

Here is the Controller class for the Calculator Service with request handler for the add operation:

@RestController
@RequestMapping("api/v1/")
public class CalculatorController {

  @Autowired
  private Calculator calculatorService;

  @RequestMapping(value = "calculator/add", method = RequestMethod.POST)
  public Result add(@RequestBody Values values) {
  int result = calculatorService.add(values.getFirstNumber(),
  values.getSecondNumber());
  return new Result(result);
  }
}

That’s it. Let’s run this service using

mvn spring-boot:run

This will launch the application. Navigate to http://localhost:8080/swagger-ui.html in a Browser window. This will show the Swagger UI with the service details. In this example it will show the Calculator service with add operation as shown in below screenshot:

swagger1

Let’s open the /api/v1/calculator/add operation. This will show details about this operation as shown in below screenshot:

swagger2

Users can try the add operation or any other operation provided by the service by submitting parameters and using the Try it out! button on the form. Here is add operation in action:

calc_service

Operations can also be further explained using various Swagger Annotations like @ApiOperation, @ApiResponse etc.

You can also define a new API from scratch in Swagger format and generate source code in over dozen different frameworks supported by the Swagger. You can play with Swagger Editor and Swagger Codegen for building new APIs at Swagger Editor



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s