Используем Swagger (OpenAPI) для документирования и спецификации контроллеров в Spring Boot на Java

Рисунок: Swagger

Введение

В современной разработке REST API важно не только писать код, но и документировать его так, чтобы:

• frontend-разработчики точно знали, какие параметры отправлять,
• QA-инженеры могли тестировать без «угадывания»,
• новые члены команды быстро вникали в логику,
• клиенты (внешние или внутренние) имели доступ к актуальной спецификации.

Swagger (ныне OpenAPI) — это стандарт и инструмент, который автоматически генерирует документацию на основе аннотаций в вашем Java-коде. В этой статье мы подробно разберём, как использовать Springdoc OpenAPI (современная замена Springfox) для документирования контроллеров, просмотра API в UI .

Почему Springdoc OpenAPI, а не Springfox?

• Springfox устарел и плохо совместим с новыми версиями Spring Boot.
• Springdoc OpenAPI — активно поддерживается, легковесен, работает «из коробки».
• Поддерживает OpenAPI 3, который богаче и современнее Swagger 2.0.

✅ Для Java 11 и Spring Boot 2.7+ — Springdoc OpenAPI является де-факто стандартом.

Шаг 1: Подключаем зависимости

Добавьте в pom.xml:

<!-- Springdoc OpenAPI UI — для генерации документации и Swagger UI -->

<dependency>

<groupId>org.springdoc</groupId>

<artifactId>springdoc-openapi-ui</artifactId>

<version>1.6.14</version> <!-- Для Java 11 и Spring Boot 2.7 -->

</dependency>

Версия 1.6.x — последняя, совместимая с Jakarta EE 8 (т.е. javax.* пакетами), что актуально для Java 11 и Spring Boot 2.x.

Готово! Больше ничего настраивать не нужно — Spring Boot автоматически включит:

• /v3/api-docs — JSON-спецификация в формате OpenAPI,
• /swagger-ui.html — веб-интерфейс для просмотра и тестирования API.

Шаг 2: Документируем контроллер и DTO

Пример DTO с аннотациями OpenAPI

Рисунок: DTO с аннотацией @Schema

@Schema — ключевая аннотация для описания полей в OpenAPI.
example — показывает пример значения в Swagger UI (удобно для тестирования!).

Пример контроллера с документацией

Рисунок: пример контроллера с документацией, часть 1

Рисунок: пример контроллера с документацией, часть 2

Ключевые аннотации:@Tag — группирует эндпоинты в UI,
@Operation — описывает сам метод,
@ApiResponse — документирует возможные HTTP-статусы,
@Parameter — описывает path/query параметры.

Шаг 3: Просмотр документации в Swagger UI

Запустите приложение и перейдите по адресу:

http://localhost:8080/swagger-ui.html

Вы увидите:

• Дерево эндпоинтов с тегами,
• Возможность открыть каждый метод,
• Поля с описанием, примерами,
• Кнопку «Try it out» — чтобы отправить реальный запрос из браузера!

✅ Это живая документация — она всегда синхронизирована с кодом.

Шаг 4: Получение OpenAPI-спецификации в JSON/YAML

JSON-спецификация доступна по:

http://localhost:8080/v3/api-docs

YAML-версия:

http://localhost:8080/v3/api-docs.yaml

Вы можете сохранить этот файл и использовать его для:

• генерации клиентского кода,
• импорта в Postman,

Заключение

Пример, рассмотренный в статье, можно найти по адресу:
https://github.com/ShkrylAndrei/blog_yandex/tree/main/src/main/java/info/shkryl/use_swagger