移除基本錯誤控制器在 SpringFox Swagger-UI 中

1. 概述

在本教程中，我們將學習多種方法來配置 Swagger，以隱藏由 BasicErrorController 暴露的路徑，在 Spring Boot 應用程序中。

2. 目標項目

本文檔不涉及使用 Spring Boot 和 Swagger-UI 創建基本配置的步驟。您可以利用已配置好的項目，或者遵循“使用 Spring REST API 設置 Swagger 2”指南來創建基本配置。

3. 問題

如果我們的代碼包含 BasicErrorController 和 Swagger，默認情況下，Swagger 會將所有其端點也包含在生成的文檔中。我們需要提供自定義配置來移除不需要的控制器。

例如，假設我們想要提供標準 RestController 的 API 文檔：

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

另外，假設我們的代碼包含一個繼承自 BasicErrorController 的類：

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

我們能看到  已包含在生成的文檔中：

4. 解決方案

在本節中，我們將探討四種不同的解決方案，用於從 Swagger 文檔中排除資源。

4.1. 使用 basePackage() 排除資源

通過指定控制器所需的 base 包，我們可以排除不需要的資源。

此功能僅在錯誤控制器的包與標準控制器的包不同時有效。在 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"))
        .build();
   }
}

使用此自定義配置，Swagger 將僅檢查指定包內的 REST Controller 方法。例如，如果我們的 BasicErrorController 定義在 “com.baeldung.swaggerconf.error” 包中，則不會被 Swagger 掃描。

4.2. 註釋説明下的排除

或者，我們也可以指示 Swagger 只生成帶有特定 Java 註解裝飾的類文檔。

在此示例中，我們將將其設置為 RestController.class：

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

在這種情況下，BasicErrorController 將從 Swagger 文檔中排除，因為它沒有使用 @RestController 註解進行裝飾。該註解則存在於我們想要文檔化的 RegularRestController 中。

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 {
   // basic constructor
}

5. 結論

在本文中，我們展示了四種不同的方法，用於在 Spring Boot 應用程序中配置 Swagger，以隱藏 BasicErrorController 資源。

知識庫 / Spring / Spring Boot RSS 訂閱