Статьи


Подключение Swagger к Spring Boot

Вернуться назад

4 октября 2020

Тэги: Spring Spring Boot Kotlin gradle

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

Подключение

Если ваше приложение основано на Spring Boot, для подключения swagger достаточно добавить всего лишь одну зависимость (пример для gradle):

implementation("io.springfox:springfox-boot-starter:3.0.0")

Теперь, если у вас есть хотя бы один эндпоинт, вы сможете просмотреть всю информацию о нём, открыв страницу http://127.0.0.1:8080/swagger-ui/ (обратите внимание, что слеш в конце обязателен). По каждому эндпоинту можно посмотреть тип запроса (GET, POST и т.п.), набор входных параметров, формат ответа, возможные коды ошибок http (200, 401, 403, 404 и т.п.). А если нажать кнопку «Try it out», то вы сможете отправить тестовый запрос прямо через веб-интерфейс.

Описание контроллера и метода

Теперь рассмотрим, как настраивать отображаемую информацию. Предположим, есть у нас такой контроллер (пример кода на kotlin):

@RestController
@RequestMapping("/hello")
class HelloController {
    @GetMapping
    fun getInfo() = TestDto(
            id = 42,
            name = "Тестовый ответ"
    )
}

Он содержит единственный обработчик GET-запроса, который при обращении по адресу http://127.0.0.1:8080/hello будет возвращать ответ в формате json. Сам формат ответа определяется дата-классом TestDto:

data class TestDto(
        val id: Int,
        val name: String
)

Теперь давайте добавим описания. Аннотация @Api с параметром description позволяет задавать описание для контроллера, а @ApiOperation - для метода. Тогда наш контроллер примет следующий вид:

@RestController
@RequestMapping("/hello")
@Api(description = "Тестовый контроллер")
class HelloController {
    @GetMapping
    @ApiOperation("Тестовый метод")
    fun getInfo(
    // ...

Теперь, если мы снова откроем страницу сваггера, то увидим там описания «Тестовый контроллер» и «Тестовый метод».

Как скрыть лишние параметры

По умолчанию swagger будет отображать все параметры, которые содержит ваш метод. Но в Spring Boot некоторые параметры могут подставляться в метод при помощи аннотаций и по факту передавать их снаружи (с клиента) не требуется. Таким параметром может быть, например, информация о пользователе, которая подгружается автоматически на основе авторизационного токена, который был передан вместе с запросом. Тогда эти параметры можно убрать из документации.

Для примера добавим в наш метод необязательный параметр (т.е. он может не передаваться с клиента) и скроем его.

@GetMapping
    @ApiOperation("Тестовый метод")
    fun getInfo(
            @RequestParam(required = false) @ApiIgnore flag: Boolean
    )
    // ...

Аннотация @RequestParam определяет сам параметр запроса под названием flag. Признак required говорит об обязательности (или необязательности) этого параметра. Аннотация @ApiIgnore исключает этот параметр из документации swagger.

Как скрыть лишние эндпоинты

Проекты, основанные на Spring Boot, часто могут содержать служебные эндпоинты (например, если вы подключили spring-boot-starter-actuator). Эти эндпоинты не имеют отношения к бизнес-логике приложения и поэтому их лучше также скрыть из документации. Для этого можно определить базовый пакет, который будет сканировать Swagger. Определим следующий бин (аннтация @Bean) в отдельном конфигурационном классе (аннотация @Configuration). Таким образом, мы немного переопределим стандартные настройки:

@Configuration
class SwaggerConfig {
    @Bean
    fun api(): Docket {
        return Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("ru.devmark.controller"))
                .paths(PathSelectors.any())
                .build()
    }
}

Все настройки swagger производятся с помощью методов объекта Docket. Обратите внимание на метод apis(), в котором указывается базовый пакет. Здесь указан пакет ru.devmark.controller. Это означает, что сваггер будет отображать только эндпоинты из этого пакета и из пакетов, вложенных в него.