🔥 Как настроить Swagger/OpenAPI для документирования API

Swagger (OpenAPI) — стандарт описания REST API. Автогенерация документации, интерактивное тестирование через UI, генерация клиентов для различных языков.

Синхронизируется с кодом автоматически, поддерживает аннотации для детального описания и используется как контракт между фронтендом и бекендом.

1️⃣ Добавляем зависимости

Для Spring Boot 3.x используйте springdoc-openapi-starter-webmvc-ui. Это современная библиотека, заменившая устаревший springfox.

Одна зависимость подтягивает всё необходимое: генерацию спецификации, Swagger UI и валидацию. Автоматически интегрируется со Spring MVC и Spring Security.

2️⃣ Создаём базовую конфигурацию

Создайте класс OpenApiConfig аннотированный @Configuration. Определите bean OpenAPI с общей информацией: название API, версия, описание, контакты, лицензия.

Используйте Info, Contact, License для метаданных. Настройте servers() для указания базовых URL разных окружений (dev, staging, prod). Это позволит тестировать через UI на любом окружении.

3️⃣ Документируем контроллеры

Используйте @Tag на классе контроллера для группировки эндпоинтов. На методах применяйте @Operation(summary, description) для описания операции.

Аннотируйте параметры через @Parameter(description, required, example). Для тела запроса используйте @io.swagger.v3.oas.annotations.parameters.RequestBody с описанием и примерами. Добавляйте @Schema на DTO для описания полей модели.

4️⃣ Описываем ответы API

Используйте @ApiResponses с набором @ApiResponse для каждого возможного HTTP статуса. Укажите responseCode, description и content с примерами.

Создайте стандартные ErrorResponse классы и документируйте их через @Schema(description). Это даст консистентную обработку ошибок и понятную документацию для клиентов API.

5️⃣ Настраиваем Security схемы

Для JWT добавьте SecurityScheme через @SecurityScheme аннотацию на конфигурации. Укажите type = BEARERAUTH, scheme = "bearer", bearerFormat = "JWT".

На защищённых эндпоинтах используйте @SecurityRequirement(name = "bearerAuth"). Swagger UI автоматически добавит поле для ввода токена и будет подставлять его в заголовок Authorization.

6️⃣ Кастомизация и расширение

Настройте springdoc.swagger-ui.path для изменения URL (по умолчанию /swagger-ui.html). Включите tryItOutEnabled и supportedSubmitMethods для удобного тестирования.

Используйте springdoc.api-docs.path для изменения пути к JSON спецификации (по умолчанию /v3/api-docs). Для группировки API используйте @RouterOperations и группировку по packages или paths.

7️⃣ Best practices и продвинутые фичи

▪️ Используйте @Hidden на методах/контроллерах для исключения из документации
▪️ Добавьте примеры запросов/ответов через @ExampleObject для лучшего UX
▪️ Генерируйте client SDK через openapi-generator-maven-plugin
▪️ В production отключайте Swagger UI или закрывайте авторизацией
▪️ Используйте springdoc.show-actuator для документирования Actuator эндпоинтов
▪️ Включите springdoc.default-consumes/produces-media-type для дефолтных типов

✔️ Что происходит под капотом

При старте приложения springdoc сканирует все контроллеры, читает аннотации Spring и OpenAPI, анализирует сигнатуры методов и типы параметров.

Из этой информации генерируется OpenAPI спецификация в формате JSON/YAML. Swagger UI читает эту спецификацию и рендерит интерактивный интерфейс с формами для тестирования и документацией.

💡 Бонус-совет

Интегрируйте OpenAPI спецификацию в CI/CD для автоматической проверки breaking changes. Используйте openapi-diff для сравнения версий API. Публикуйте спецификацию в artifact repository для использования клиентами при генерации SDK.

🔹 Курс «Алгоритмы и структуры данных»
🔹 Получить консультацию менеджера
🔹 Сайт Академии 🔹 Сайт Proglib

🐸 Библиотека джависта

#Enterprise

🐸 Библиотека джависта

#DevLife