Перейти на PRO

Используете ли вы Swagger/OpenAPI аннотации для документирования REST-контроллеров?

Тип вопроса: Spring Вероятность: 10% Категория: Java Разработчик

Ответ

Да, активно использую. Аннотации SpringDoc OpenAPI (для Swagger UI 3.x) — это стандартный способ генерации живой документации и спецификации OpenAPI для REST API.

Основные аннотации и их назначение:

  1. Документирование контроллера (@Tag):

    @Tag(name = "User Management", description = "API для управления пользователями")
@RestController
@RequestMapping("/api/users")
public class UserController { ... }

  2. Документирование операции (@Operation):

    @Operation(
    summary = "Получить пользователя по ID",
    description = "Возвращает полные данные пользователя, включая профиль."
)
@GetMapping("/{id}")
public ResponseEntity<UserDto> getUser(@PathVariable Long id) { ... }

  3. Описание параметров (@Parameter):

    @Parameter(description = "Уникальный идентификатор пользователя", required = true, example = "123")
@PathVariable Long id

  4. Описание ответов (@ApiResponse):

    @ApiResponse(responseCode = "200", description = "Пользователь найден")
@ApiResponse(responseCode = "404", description = "Пользователь с указанным ID не найден")

Преимущества подхода:

  • Автоматическая актуализация: Документация всегда соответствует коду.
  • Интерактивное тестирование: Swagger UI позволяет отправлять реальные запросы.
  • Генерация клиентского кода: Спецификация OpenAPI используется такими инструментами, как OpenAPI Generator, для создания клиентских SDK.
  • Валидация контракта: Помогает гарантировать, что API соответствует заявленной схеме.

Техническая реализация: Достаточно добавить зависимость springdoc-openapi-starter-webmvc-ui, и документация будет доступна по пути /swagger-ui.html.

Ответ 18+ 🔞

А, ну так ты про эти ваши аннотации для Swagger'а спрашиваешь! Да, конечно, использую, а как же. Это ж, блядь, не 2007-й год на дворе, чтобы вручную в wiki или, прости господи, в Word'е документацию писать. Это же, ёпта, каменный век!

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

  1. Воткнул на контроллер бирку (@Tag):

    @Tag(name = "Управление юзерами", description = "Тут мы этих пользователей создаём, удаляем и вообще ебём им мозги")
@RestController
@RequestMapping("/api/users")
public class UserController { ... }

    Чтобы сразу было понятно — это не про платежи, а конкретно про юзеров. Элементарно, Ватсон!

  2. Каждому методу — описание операции (@Operation):

    @Operation(
    summary = "Достать пользователя по айдишнику",
    description = "Выдаст все данные, какие есть. Если, конечно, этот бедолага вообще существует, а не удалён в тартарары."
)
@GetMapping("/{id}")
public ResponseEntity<UserDto> getUser(@PathVariable Long id) { ... }

    А то без этого другой разработчик подойдёт и спросит: «А этот GET /api/users/123 что, блядь, возвращает? Кошелек или температуру процессора?». А ты такой: «Читай документацию, пидарас шерстяной!».

  3. Параметры тоже не сами по себе летают (@Parameter):

    @Parameter(description = "Уникальный айди юзера. Не путай с номером карты!", required = true, example = "123")
@PathVariable Long id

    Чтобы не было потом: «Ой, а я строку передал, а оно не работает!». Да потому что Long надо, вротберунчик!

  4. И что он тебе в ответ плюнет — тоже описывай (@ApiResponse):

    @ApiResponse(responseCode = "200", description = "Ура, нашли! Вот он, красавец.")
@ApiResponse(responseCode = "404", description = "Не-а. Такого юзера нет. Может, сам его удалил и забыл?")

    А то без этого фронтендер будет в истерике: «Мне твой сервер 500 Internal Server Error шлёт, когда юзера нет!». А это не ошибка сервера, это, блядь, 404 Not Found должен быть! Всё по канону!

И зачем этот весь цирк, спросишь? А затем:

  • Документация сама себя пишет. Ты код поменял — она обновилась. Никакого «ой, я забыл в конфлюенс страничку поправить». Волшебство, ёпта!
  • Можно сразу тыкать кнопочки в Swagger UI и проверять. Не надо Postman настраивать, не надо curl'ить в консоли. Нажал — отправил — получил. Красота!
  • Из этой штуки можно потом клиентские либы на всех языках нагенерировать. Ну, типа, для мобильщиков или для того же фронта. Автоматом, блядь!
  • Все в одной песочнице играют. И бэкенд, и фронтенд смотрят на одну схему и понимают, кто кому и что должен передавать. Меньше споров, кто виноват, что данные не пришли.

Технически-то что делать? Да хуйня вопрос! Кинул в pom.xml зависимость springdoc-openapi-starter-webmvc-ui, запустил приложение — и всё, пиздец. Документация сама по адресу /swagger-ui.html всплывёт, как чёрт из табакерки. Никаких танцев с бубном.

© ХакСобесов, 2026
support@hacksobesov.com