Статьи
Утилиты Telegram YouTube Отзывы

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

Видеогайд

3 октября 2020

Тэги: gradle, Kotlin, Spring, Spring Boot, YouTube.

Содержание

  1. Подключение
  2. Описание контроллера и метода
  3. Как скрыть лишние параметры
  4. Как скрыть лишние эндпоинты

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

Внимание! Для последних версий Spring Boot данная статья уже не актуальна. См. статью Springdoc для документации REST API.

Помимо данной статьи вы можете также посмотреть видеогайд на эту тему.

Подключение

Если ваше приложение основано на 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. Это означает, что сваггер будет отображать только эндпоинты из этого пакета и из пакетов, вложенных в него.



Комментарии

17.03.2021 16:06 Ян

Спасибо! Статья пригодилась.

15.05.2021 13:50 Мурад

Благодарю. Полезно!

29.09.2022 16:27 Михаил

бред сивой кобылы а не статья

30.09.2022 02:05 devmark

Михаил, как можно улучшить качество данной статьи?

04.01.2023 21:07 Anton

Чет фигня какая-то) не работает ничерта

22.04.2023 12:43 Mark

Маловато инфы

27.04.2023 17:22 .

"Если ваше приложение основано на Spring Boot, для подключения swagger достаточно добавить всего лишь одну зависимость"
добавил зависимость.
ничё не появилось. да, со слешем в конце, ага.
да, спринг бут. да, при запросе по апи контроллера json возвращается. ага, @Api тоже добавил, никакой свягер не заработал.

Добавить комментарий

×

devmark.ru