Swagger/OpenAPI генерация для Java: обзор библиотек |…

Swagger/OpenAPI генерация для Java: полное руководство по инструментам

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

Что такое Swagger и OpenAPI?

Swagger — это набор инструментов для проектирования, создания и документирования REST API. OpenAPI — это спецификация, которая определяет стандарт описания API. Swagger является самой популярной реализацией этой спецификации.

Основные библиотеки для Java

Рассмотрим три ключевых инструмента:

SpringDoc OpenAPI — современная библиотека для Spring Boot
Swagger Core — базовая библиотека от создателей Swagger
OpenAPI Generator — инструмент для генерации кода и документации

1. SpringDoc OpenAPI

SpringDoc — это наиболее популярный выбор для проектов на Spring Boot. Он автоматически интегрируется с вашим приложением и генерирует документацию на основе аннотаций и типов данных.

Установка и настройка

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

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

Пример использования

Создайте простой контроллер с документацией:

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

    @GetMapping("/{id}")
    @Operation(summary = "Получить пользователя по ID")
    public ResponseEntity<User> getUser(
            @Parameter(description = "ID пользователя")
            @PathVariable Long id) {
        // реализация
        return ResponseEntity.ok(new User(id, "Иван"));
    }

    @PostMapping
    @Operation(summary = "Создать нового пользователя")
    public ResponseEntity<User> createUser(
            @RequestBody @Valid CreateUserRequest request) {
        // реализация
        return ResponseEntity.status(201).body(new User(1L, request.getName()));
    }
}

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

2. Swagger Core

Библиотека Swagger Core предоставляет более низкоуровневый подход к созданию спецификации OpenAPI. Она подходит для проектов, где требуется полный контроль над генерацией.

Пример создания спецификации вручную

import io.swagger.v3.oas.models.*;
import io.swagger.v3.oas.models.info.*;

OpenAPI openAPI = new OpenAPI()
    .info(new Info()
        .title("Pet Store API")
        .description("API для управления питомцами")
        .version("1.0.0")
        .contact(new Contact()
            .name("Разработчик")
            .email("dev@example.com")))
    .addServersItem(new Server()
        .url("https://api.example.com/v1")
        .description("Production сервер"));

// Добавление путей и компонентов
Paths paths = new Paths();
paths.addPathItem("/pets", new PathItem()
    .get(new Operation()
        .operationId("listPets")
        .summary("Получить список питомцев")));
openAPI.setPaths(paths);

3. OpenAPI Generator

OpenAPI Generator — это инструмент, который может генерировать как документацию, так и клиентский/серверный код на основе спецификации OpenAPI.

Использование в Maven

Добавьте плагин в pom.xml:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.6.0</version>
    <executions>
        <execution>
            <goals><goal>generate</goal></goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <output>${project.build.directory}/generated-sources</output>
            </configuration>
        </execution>
    </executions>
</plugin>