1. Обзор
В этом руководстве мы изучим несколько методов настройки Swagger в приложении Spring Boot , чтобы скрыть пути, открытые BasicErrorController .
2. Целевой проект
В этой статье мы не будем рассматривать создание базовой конфигурации для запуска Spring Boot и Swagger-UI. Мы можем либо использовать уже настроенный проект, либо следовать руководству по настройке Swagger 2 с помощью Spring REST API , чтобы создать базовую конфигурацию.
3. Проблема
Если наш код содержит BasicErrorController, Swagger по умолчанию также включит все его конечные точки в сгенерированную документацию. Нам нужно предоставить пользовательскую конфигурацию для удаления нежелательных контроллеров.
Например, предположим, что мы хотели бы предоставить документацию API стандартного 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
}
Кроме того, давайте предположим, что наш код включает класс, расширяющий BasicErrorController :
@Component
@RequestMapping("my-error-controller")
public class MyErrorController extends BasicErrorController {
// basic constructor
}
Мы видим, что my-error-controller включен в сгенерированную документацию:
4. Решения
В этом разделе мы рассмотрим четыре различных решения для исключения ресурсов из документации Swagger.
4.1. Исключить с помощью basePackage()
Указав базовый пакет контроллеров, которые мы хотим задокументировать, мы можем исключить ресурсы, которые нам не нужны.
Это работает только тогда, когда пакет контроллера ошибок отличается от стандартного пакета контроллера. С Spring Boot достаточно предоставить bean-компонент Docket :
@Configuration
public class SwaggerConfiguration {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.foreach.swaggerconf.controller"))
.build();
}
}
При наличии этой настраиваемой конфигурации Swagger будет проверять наличие методов REST Controller только внутри указанного пакета. Так, например, если наш BasicErrorController определен в пакете « com.foreach.swaggerconf.error », он учитываться не будет.
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
Наконец, мы можем исключить определенный класс из Swagger, используя аннотацию @ApiIgnore : ``
@Component
@RequestMapping("my-error-controller")
@ApiIgnore
public class MyErrorController extends BasicErrorController {
// basic constructor
}
5. Вывод
В этой статье мы представили четыре различных способа настройки Swagger в приложении Spring Boot для скрытия ресурсов BasicErrorController .
Как всегда, полный код доступен на GitHub .