Статьи
YouTube-канал

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

Видеогайд

3 октября 2020

Тэги: gradle Kotlin Spring Spring Boot YouTube

Содержание

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

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


Облако тэгов

Kotlin, Java, Java 16, Java 11, Java 10, Java 9, Java 8, Spring, Spring Boot, Spring Data, SQL, PostgreSQL, Oracle, Hibernate, Collections, Stream API, многопоточность, ввод-вывод, Apache, maven, gradle, JUnit, YouTube, новости, ООП, алгоритмы, головоломки, rest, GraphQL, Excel, XML, json, yaml

Последние статьи


Комментарии

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

15.05.2021 13:50 Мурад

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

17.03.2021 16:06 Ян

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

×

devmark.ru