Generic Top

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:

>> CHECK OUT THE COURSE

1. Overview

In this tutorial, we’ll learn multiple methods to configure Swagger in a Spring Boot application to hide paths exposed by the BasicErrorController.

2. Target Project

We will not cover creating the basic configuration to start with Spring Boot and Swagger-UI in this article. We can either use an already-configured project or follow the Setting Up Swagger 2 with a Spring REST API guide to create the basic configuration.

3. The Problem

If our code contains a BasicErrorController, Swagger, by default, will include all its endpoints also in the generated documentation. We need to provide a custom configuration to remove unwanted controllers.

For example, let's say that we would like to provide the API documentation of a standard RestController:

@RestController
@RequestMapping("good-path")
public class RegularRestController {
   
   @ApiOperation(value = "This method is used to get the author name.")
   @GetMapping("/getAuthor")
   public String getAuthor() {
       return "Name Surname";
   }
   
   // Other similar methods
}

Also, let's suppose our code includes a class that extends the BasicErrorController:

@Component
@RequestMapping("my-error-controller")
public class MyErrorController extends BasicErrorController {
    // basic constructor
}

We can see that my-error-controller is included in the generated documentation:

4. The Solutions

In this section, we'll look at four different solutions to exclude resources from the Swagger documentation.

4.1. Exclude with basePackage()

By specifying the base package of the controllers we want to document, we can exclude resources that we don't need.

This works only when the error controller package is different from the standard controller's package. With Spring Boot, it's enough if we provide a Docket bean:

@Configuration
public class SwaggerConfiguration {
   
   @Bean
   public Docket api() {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.baeldung.swaggerconf.controller"))
        .build();
   }
}

With this custom configuration in place, Swagger will check for REST Controller methods only inside the specified package. So, for example, if our BasicErrorController is defined in the package “com.baeldung.swaggerconf.error“, it will not be considered.

4.2. Exclude with Annotations

Alternatively, we could also indicate that Swagger has to generate documentation only of classes decorated with a specific Java annotation.

In this example, we'll set it to RestController.class:

@Bean
public Docket api() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
     .select()
     .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
     .build();
}

In this case, the BasicErrorController will be excluded from Swagger documentation because it's not decorated with the @RestController annotation. This annotation is instead present on the RegularRestController we would like to document.

4.3. Exclude with Regex on Path

Another approach is to specify a regex on a custom path. In this case, only resources mapped to the “/good-path” prefix will be documented:

@Bean
public Docket api() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
     .select()
     .paths(regex("/good-path/.*"))
     .build();
}

4.4. Exclude with @ApiIgnore

Lastly, we can exclude a specific class from Swagger by using the annotation @ApiIgnore:

@Component
@RequestMapping("my-error-controller")
@ApiIgnore 
public class MyErrorController extends BasicErrorController {
   // basic constructor
}

5. Conclusion

In this article, we presented four different ways to configure Swagger in a Spring Boot application to hide BasicErrorController resources.

As always, the complete code is available over on GitHub.

Generic bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:

>> CHECK OUT THE COURSE
Generic footer banner
Comments are closed on this article!