Что такое Swagger (OpenAPI) для REST API?

Swagger (ныне часть инициативы OpenAPI) — это фреймворк для описания, документирования, тестирования и визуализации RESTful API. Основной инструмент — Swagger UI, который генерирует интерактивную HTML-документацию на основе спецификации OpenAPI.

Ключевые преимущества:

• Единый источник истины: Спецификация API (в YAML/JSON) синхронизирует документацию между фронтендом и бэкендом.
• Интерактивное тестирование: Позволяет отправлять реальные HTTP-запросы прямо из браузера.
• Автогенерация: Код клиентов и серверов может генерироваться из спецификации.

Пример аннотаций для Spring Boot (Springfox):

@RestController
@RequestMapping("/api/users")
@Api(tags = "User Management") // Описание группы операций
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = "Get user by ID", notes = "Returns a single user")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Success", response = User.class),
        @ApiResponse(code = 404, message = "User not found")
    })
    public ResponseEntity<User> getUser(
            @ApiParam(value = "User ID", required = true, example = "123")
            @PathVariable Long id) {
        // ... логика
    }
}

Типичный стек и настройка для Spring Boot:

1. Добавить зависимость (например, springdoc-openapi-ui для Spring Boot 3+).
2. Документация автоматически генерируется на основе аннотаций и структуры контроллеров.
3. После запуска приложения документация доступна по адресу:
   • Swagger UI: http://localhost:8080/swagger-ui.html
   • Спецификация OpenAPI (JSON): http://localhost:8080/v3/api-docs

Это значительно упрощает процесс разработки, тестирования и интеграции API.