3 октября 2020
Тэги: gradle, Kotlin, Spring Boot, YouTube.
Swagger – это библиотека, которая при подключении к вашему проекту раз и навсегда решает вопрос актуальности технической документации. Swagger автоматически сканирует все эндпоинты вашего проекта, доступные снаружи, и отображает подробную информацию о них в веб-интерфейсе. Как только вы меняете существующие эндпоинты или добавляете новые – swagger тут же начинает отображать эти изменения. Кроме справочной информации, swagger также позволяет отправлять запросы в тестовых целях прямо через веб-интерфейс.
Внимание! Для последних версий Spring Boot данная статья уже не актуальна. См. статью Springdoc для документации REST API.
Помимо данной статьи вы можете также посмотреть видеогайд на эту тему.
Если ваше приложение основано на Spring Boot, для подключения swagger достаточно добавить всего лишь одну зависимость (пример для gradle):
Теперь, если у вас есть хотя бы один эндпоинт, вы сможете просмотреть всю информацию о нём, открыв страницу http://127.0.0.1:8080/swagger-ui/ (обратите внимание, что слеш в конце обязателен). По каждому эндпоинту можно посмотреть тип запроса (GET, POST и т.п.), набор входных параметров, формат ответа, возможные коды ошибок http (200, 401, 403, 404 и т.п.). А если нажать кнопку «Try it out», то вы сможете отправить тестовый запрос прямо через веб-интерфейс.
Теперь рассмотрим, как настраивать отображаемую информацию. Предположим, есть у нас такой контроллер (пример кода на kotlin):
Он содержит единственный обработчик GET-запроса, который при обращении по адресу http://127.0.0.1:8080/hello будет возвращать ответ в формате json. Сам формат ответа определяется дата-классом TestDto:
Теперь давайте добавим описания. Аннотация @Api с параметром description позволяет задавать описание для контроллера, а @ApiOperation – для метода. Тогда наш контроллер примет следующий вид:
Теперь, если мы снова откроем страницу сваггера, то увидим там описания «Тестовый контроллер» и «Тестовый метод».
По умолчанию swagger будет отображать все параметры, которые содержит ваш метод. Но в Spring Boot некоторые параметры могут подставляться в метод при помощи аннотаций и по факту передавать их снаружи (с клиента) не требуется. Таким параметром может быть, например, информация о пользователе, которая подгружается автоматически на основе авторизационного токена, который был передан вместе с запросом. Тогда эти параметры можно убрать из документации.
Для примера добавим в наш метод необязательный параметр (т.е. он может не передаваться с клиента) и скроем его.
Аннотация @RequestParam определяет сам параметр запроса под названием flag. Признак required говорит об обязательности (или необязательности) этого параметра. Аннотация @ApiIgnore исключает этот параметр из документации swagger.
Проекты, основанные на Spring Boot, часто могут содержать служебные эндпоинты (например, если вы подключили spring-boot-starter-actuator). Эти эндпоинты не имеют отношения к бизнес-логике приложения и поэтому их лучше также скрыть из документации. Для этого можно определить базовый пакет, который будет сканировать Swagger. Определим следующий бин (аннтация @Bean) в отдельном конфигурационном классе (аннотация @Configuration). Таким образом, мы немного переопределим стандартные настройки:
Все настройки swagger производятся с помощью методов объекта Docket. Обратите внимание на метод apis(), в котором указывается базовый пакет. Здесь указан пакет ru.devmark.controller. Это означает, что сваггер будет отображать только эндпоинты из этого пакета и из пакетов, вложенных в него.
Kotlin, Java, Spring, Spring Boot, Spring Data, SQL, PostgreSQL, Oracle, Linux, Hibernate, Collections, Stream API, многопоточность, файлы, Nginx, Apache, maven, gradle, JUnit, YouTube, новости, руководство, ООП, алгоритмы, головоломки, rest, GraphQL, Excel, XML, json, yaml.
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 тоже добавил, никакой свягер не заработал.