OpenAPI / Swagger Java: методы, примеры, установка |…

Что такое OpenAPI / Swagger и зачем это нужно Java-разработчику?

OpenAPI (ранее известный как Swagger) — это спецификация для описания, создания, документирования и потребления RESTful API. Для Java-разработчика библиотеки OpenAPI / Swagger — это незаменимый инструмент, который автоматизирует процесс документирования API и генерации клиентского кода.

Основные причины использовать OpenAPI / Swagger в Java-проектах:

Автоматическая генерация документации — библиотека анализирует ваш код (аннотации Spring Boot, JAX-RS) и создает интерактивную документацию в формате Swagger UI.
Стандартизация — единый формат описания API, понятный как людям, так и машинам.
Генерация клиентского кода — можно сгенерировать Java-клиент для любого API, описанного в OpenAPI.
Тестирование — Swagger UI позволяет выполнять запросы к API прямо из браузера.
Интеграция с CI/CD — можно проверять соответствие API спецификации на этапе сборки.

В этой статье мы рассмотрим две основные Java-библиотеки: springdoc-openapi (для Spring Boot) и Swagger Core (для JAX-RS и других фреймворков).

Установка библиотеки OpenAPI / Swagger для Java

Установка зависит от используемого фреймворка. Рассмотрим два основных варианта.

Вариант 1: Spring Boot (springdoc-openapi)

Добавьте зависимость в ваш pom.xml (Maven):

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

Для Gradle (build.gradle):

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

Вариант 2: JAX-RS / Jakarta (Swagger Core)

Maven:

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2-jakarta</artifactId>
    <version>2.2.22</version>
</dependency>

Gradle:

implementation 'io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.22'

Быстрый старт: первый пример с Spring Boot

После добавления зависимости springdoc-openapi в Spring Boot проект, Swagger UI автоматически доступен по адресу http://localhost:8080/swagger-ui.html. Создадим простой контроллер:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

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

    @GetMapping("/{id}")
    @Operation(summary = "Получить пользователя по ID")
    public String getUser(@PathVariable Long id) {
        return "User with ID: " + id;
    }

    @PostMapping
    @Operation(summary = "Создать нового пользователя")
    public String createUser(@RequestBody String userName) {
        return "Created user: " + userName;
    }
}

После запуска приложения откройте http://localhost:8080/swagger-ui.html — вы увидите интерактивную документацию с возможностью выполнять запросы.

Основные методы и аннотации OpenAPI / Swagger для Java

Рассмотрим 10 ключевых аннотаций и методов из библиотеки io.swagger.v3.oas.annotations.

1. @Operation

Что делает: Описывает отдельный эндпоинт (метод API). Добавляет описание, summary, теги и идентификатор операции.

Параметры:

summary — краткое описание
description — подробное описание
operationId — уникальный идентификатор
tags — массив тегов для группировки
deprecated — пометить как устаревший

Пример:

@GetMapping("/search")
@Operation(
    summary = "Поиск пользователей",
    description = "Ищет пользователей по имени и возрасту",
    operationId = "searchUsers",
    tags = {"User Search"}
)
public List<String> searchUsers(@RequestParam String name, @RequestParam int age) {
    return Arrays.asList("User1", "User2");
}

2. @ApiResponse

Что делает: Описывает возможный HTTP-ответ от эндпоинта. Позволяет задать код ответа, описание и схему данных.

Параметры:

responseCode — HTTP код (например, "200", "404")
description — описание ответа
content — содержимое ответа (массив @Content)

Пример:

@GetMapping("/{id}")
@Operation(summary = "Получить пользователя")
@ApiResponse(responseCode = "200", description = "Пользователь найден")
@ApiResponse(responseCode = "404", description = "Пользователь не найден")
public User getUser(@PathVariable Long id) {
    // логика
}

3. @Tag

Что делает: Группирует эндпоинты по логическим категориям. Можно применять на уровне класса или метода.

Параметры:

name — название тега
description — описание группы
externalDocs — внешняя документация

Пример:

@RestController
@RequestMapping("/api/orders")
@Tag(name = "Orders", description = "Управление заказами")
public class OrderController {
    // методы
}

4. @Schema

Что делает: Описывает модель данных (DTO, entity). Позволяет задать описание полей, примеры значений, ограничения.

Параметры:

description — описание поля
example — пример значения
required — обязательное поле
minimum/maximum — числовые ограничения
pattern — регулярное выражение

Пример:

public class UserDto {
    @Schema(description = "Уникальный идентификатор", example = "1")
    private Long id;

    @Schema(description = "Имя пользователя", example = "Иван", required = true)
    private String name;

    @Schema(description = "Email", example = "ivan@example.com", pattern = "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$")
    private String email;
}

5. @Parameter

Что делает: Описывает параметры запроса (path, query, header, cookie). Позволяет задать описание, обязательность, пример.

Параметры:

name — имя параметра
description — описание
required — обязательный
in — где находится параметр (PATH, QUERY, HEADER, COOKIE)
example — пример значения

Пример:

@GetMapping("/filter")
@Operation(summary = "Фильтр пользователей")
public List<User> filterUsers(
    @Parameter(description = "Минимальный возраст", example = "18", required = true)
    @RequestParam int minAge,
    
    @Parameter(description = "Город", example = "Москва")
    @RequestParam(required = false) String city
) {
    // логика
}

6. @RequestBody

Что делает: Описывает тело запроса. Позволяет задать описание, обязательность, пример содержимого.

Параметры:

description — описание тела
required — обязательно ли тело
content — массив @Content с медиа-типами

Пример:

@PostMapping("/create")
@Operation(summary = "Создать пользователя")
public User createUser(
    @RequestBody(description = "Данные нового пользователя", required = true)
    @Valid @RequestBody UserDto userDto
) {
    // логика
}

7. @Content

Что делает: Описывает медиа-тип и схему для тела запроса или ответа. Используется внутри @ApiResponse и @RequestBody.

Параметры:

mediaType — MIME-тип (например, "application/json")
schema — ссылка на @Schema
examples — массив примеров

Пример:

@ApiResponse(
    responseCode = "200",
    description = "Успешный ответ",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = UserDto.class)
    )
)

8. @Hidden

Что делает: Скрывает метод, параметр или модель из документации Swagger. Полезно для внутренних эндпоинтов.

Параметры: нет

Пример:

@Hidden
@GetMapping("/internal/health")
public String healthCheck() {
    return "OK";
}

9. @SecurityRequirement

Что делает: Указывает, какие механизмы безопасности требуются для доступа к эндпоинту (JWT, Basic Auth, OAuth2).

Параметры:

name — название схемы безопасности
scopes — массив scope (для OAuth2)

Пример:

@GetMapping("/admin")
@Operation(summary = "Админский эндпоинт")
@SecurityRequirement(name = "bearerAuth")
public String adminEndpoint() {
    return "Admin data";
}

10. @OpenAPIDefinition

Что делает: Задает глобальные метаданные API: название, версию, описание, контактную информацию, лицензию.

Параметры:

info — объект @Info (title, version, description)
servers — массив серверов
security — глобальные схемы безопасности

Пример:

@OpenAPIDefinition(
    info = @Info(
        title = "My API",
        version = "1.0.0",
        description = "Документация для моего REST API",
        contact = @Contact(
            name = "Поддержка",
            email = "support@example.com"
        ),
        license = @License(
            name = "Apache 2.0",
            url = "http://springdoc.org"
        )
    ),
    servers = @Server(
        url = "https://api.example.com",
        description = "Production server"
    )
)
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}