Описываешь ли контроллеры с помощью Swagger-аннотаций

Да, Swagger-аннотации помогают документировать API и автоматически генерировать OpenAPI-спецификацию. Основные аннотации:

1. @Tag – для описания контроллера:

@Tag(name = "User API", description = "Operations with users")
@RestController
@RequestMapping("/users")
public class UserController { ... }

2. @Operation – для методов:

@Operation(summary = "Get user by ID", description = "Returns a single user")
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) { ... }

3. @ApiResponse – для описания ответов:

@ApiResponse(responseCode = "404", description = "User not found")

4. @Parameter – для параметров:

@Parameter(description = "ID of user", required = true)

Преимущества:

• Автогенерация документации
• Валидация схемы
• Интерактивное тестирование через Swagger UI

Для работы нужно подключить зависимость springdoc-openapi-starter-webmvc-ui и настроить @OpenAPIDefinition.