在 Swagger 文档中移除 BasicErrorController

教程

1、概览

本文将带你了解如何 Swagger 文档界面中隐藏 BasicErrorController。

3、问题

如果应用中包含了一个 BasicErrorController，Swagger 默认会将其所有端点也包含在生成的文档中。

我们需要提供自定义配置来移除不需要的 Controller。

例如，项目中的 Rest Controller 如下：

@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";
   }
}

另外，还包含一个继承 BasicErrorController 的 Error Controller：

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

启动应用，访问文档！你可以看到，my-error-controller 包含在生成的文档中：

swagger 文档界面

4、解决办法

有四种方式可以从 Swagger 文档中排除资源。

4.1、通过 basePackage() 方法排除

通过指定 Controller 所在的包，可以排除其他不需要的资源。

只有当 Error Controller 和 Rest Controller 在不同包时，这种方法才有效。在 Spring Boot 中，只要提供一个 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")) // Rest Controller 所在的包
        .build();
   }
}

如上，Swagger 将只扫描指定包内的 REST Controller。假如 BasicErrorController 定义在 com.baeldung.swaggerconf.error 包中，那么它会被忽略。

4.2、通过指定注解排除

可以通过配置让 Swagger 只扫描带有指定注解的 Rest Controller。

例如，只扫描有 @RestController 注解的 Controller：

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

由于 BasicErrorController 没有使用 @RestController，所以它会被忽略。但是其他要生成文档的 Controller 要记得添加此注解。

4.3、使用正则通过路径排除

另一种方法是在自定义路径上指定一个正则表达式。

如下，只有映射到 /good-path 前缀的资源才会被记录到文档：

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

4.4、通过 @ApiIgnore 注解排除

最后，更简单的方式是使用 @ApiIgnore 注解从 Swagger 中排除特定类：

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

5、总结

本文介绍了在 Spring Boot 应用中配置 Swagger 以隐藏 BasicErrorController 文档的四种不同方法。

参考：https://www.baeldung.com/spring-swagger-remove-error-controller