Swagger — это мощная платформа для документирования API, позволяющая разработчикам описывать структуру и функциональность своих API в стандартизированном формате. Однако существуют сценарии, в которых вы можете захотеть исключить определенные контроллеры из документирования в Swagger. В этой статье мы рассмотрим различные методы достижения этой цели и предоставим примеры кода для каждого подхода.

Метод 1: использование аннотаций Swagger
Swagger предоставляет аннотации, которые можно использовать для управления документацией определенных конечных точек или контроллеров. Используя эти аннотации, вы можете исключить появление определенных контроллеров в документации Swagger.

Пример:

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api")
@Api(hidden = true)
public class IgnoredController {
    // Controller logic goes here
}

В приведенном выше примере аннотация @Api(hidden = true)добавляется к классу IgnoredController. Эта аннотация указывает Swagger исключить контроллер из созданной документации.

Метод 2: использование конфигурации Swagger
Если вы предпочитаете более централизованный подход, вы можете настроить Swagger на игнорирование определенных контроллеров с помощью файла конфигурации Swagger.

Пример (Swagger 2.0):

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api"))
                .paths(PathSelectors.any())
                .build()
                .ignoredParameterTypes(IgnoredController.class);
    }
}

В приведенном выше примере метод ignoredParameterTypes()используется для указания класса IgnoredController. Это настраивает Swagger на исключение указанного контроллера из созданной документации.

Метод 3: использование пользовательской группировки Swagger
Другой подход — создать пользовательские группы Swagger и выборочно включать или исключать контроллеры из каждой группы. Этот метод позволяет вам иметь детальный контроль над документацией ваших контроллеров.

Пример:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket allApis() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket publicApis() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Public APIs")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api.public"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket privateApis() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Private APIs")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api.private"))
                .paths(PathSelectors.any())
                .build()
                .ignoredParameterTypes(IgnoredController.class);
    }
}

В этом примере мы создали две группы Swagger: «Публичные API» и «Частные API». Мы включаем все контроллеры в группу «Публичные API», исключая IgnoredControllerиз группы «Частные API».

В этой статье мы рассмотрели несколько методов игнорирования определенных контроллеров в документации Swagger. Используя аннотации Swagger, параметры конфигурации или пользовательскую группировку, вы можете иметь детальный контроль над тем, что документируется. Выберите метод, который лучше всего соответствует требованиям вашего проекта, и сохраняйте краткую и конкретную документацию по API.