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

Да, активно использую. Аннотации 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.