Spring Boot - Swagger 2 Set up

Posted on In

Lets learn how to set up Swagger for a Spring Boot application.

Swagger makes it easy to document Restful API. You can visit Swagger’s Homepage to get more information about Swagger.

Maven

First need to add maven dependency for springfox-swagger2. Springfox is an implementation for Swagger. 

1
2
3
4
5
6
7
8
9
10
11
<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>

Java Configuration

You can enable Swagger using @EnableSwagger2 annotation

1
2
3
4
5
6
7
8
9
10
11
12
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

Here Docket is a builder which is intended to be the primary interface into the Springfox framework. Provides sensible defaults and convenience methods for configuration.

Here are the methods used

  • Docket.select() - returns an instance of ApiSelectorBuilder to give fine grained control over the endpoints exposed via swagger.
  • ApiSelectorBuilder.apis() - allows selection of RequestHandler’s using a predicate. The example here uses an any predicate (default). Out of the box predicates provided are any, none, withClassAnnotation, withMethodAnnotation and basePackage.
  • ApiSelectorBuilder.paths() - allows selection of Path’s using a predicate. The example here uses an any predicate (default). Out of the box Springfox provide predicates regex, ant, any, none.
  • ApiSelectorBuilder.build() - builds a Docket

RequestHandlerSelectors and PathSelectors are both predicates. You can use any() for both. You can customize by selecting the package used or path.

Swagger Usage

All Swagger annotations are documented here.

Controller with Swagger API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
@RestController
@Api(value="GreetingAPI")
@RequestMapping("/greeting")
public class MyController {
	@RequestMapping(value = "/sayHello", 
			params = "firstName",
			method = RequestMethod.GET, 
			produces = MediaType.APPLICATION_JSON_VALUE)
	@ApiOperation(value="simply say hello to someone")
	public ResponseEntity<Greeting> sayHello(
	        @ApiParam(value="Whom to say hello to")
	        @RequestParam(value = "firstName") String firstName) {
		return ResponseEntity.status(HttpStatus.OK).body(new Greeting(firstName));
	}
    
    ...
}

Swagger UI Url will be http://localhost:8080/context-root/swagger-ui.html. In our case, the Url will be http://localhost:8080/swagger-ui.html

API Info

You can set the API Info for the API. These information will appear in the UI.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("My API Description")
                .contact(new springfox.documentation.service.Contact("John Doe", "www.example.com", "john@example.com"))
                .build();
    }
}

Response Customization

You can customize the Response Message section. Here is the example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2).select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.any())
            .build().apiInfo(apiInfo())
            .useDefaultResponseMessages(false)                                   
            .globalResponseMessage(RequestMethod.GET,                     
              Arrays.asList(new ResponseMessageBuilder()   
                .code(500)
                .message("500 message")
                .responseModel(new ModelRef("Error"))
                .build(),
                new ResponseMessageBuilder() 
                  .code(403)
                  .message("Forbidden!")
                  .build()));
}

The Resulting API:

Reference

For more information on Springfox, see

Sourcecode - SpringBootExamples - web-application