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

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

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

Что такое OpenAPI и зачем он нужен?

OpenAPI — это спецификация, описывающая RESTful API в формате JSON или YAML. Она включает:

• список эндпоинтов и HTTP-методов;
• модели данных (схемы запросов и ответов);
• параметры (query, path, header);
• информацию об аутентификации и авторизации.

Документация, сгенерированная по OpenAPI, позволяет автоматически создавать клиентские SDK, проводить тестирование и поддерживать актуальность описания API. Для Java существует несколько зрелых решений.

1. SpringDoc OpenAPI (рекомендуется для Spring Boot)

SpringDoc — самая популярная библиотека для генерации OpenAPI 3 в экосистеме Spring. Она автоматически сканирует контроллеры, аннотации @RequestMapping, @GetMapping и т.д., и на их основе строит спецификацию.

Подключение (Maven)

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

Пример контроллера с аннотациями

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "Получить пользователя по ID")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Пользователь найден"),
        @ApiResponse(responseCode = "404", description = "Пользователь не найден")
    })
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        // логика
        return ResponseEntity.ok(new User(id, "Иван", "ivan@example.com"));
    }
}

После запуска приложения документация доступна по адресу /swagger-ui.html, а спецификация в JSON — по /v3/api-docs.

2. Swagger Core (OpenAPI 3.0)

Swagger Core — это низкоуровневая библиотека от создателей спецификации. Она позволяет программно строить объекты OpenAPI и сериализовать их в JSON/YAML. Подходит для случаев, когда нужно тонкое управление генерацией.

Пример программного создания спецификации

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

OpenAPI openAPI = new OpenAPI()
    .info(new Info()
        .title("Пример API")
        .version("1.0.0")
        .description("Документация, созданная вручную"))
    .path("/hello", new PathItem()
        .get(new Operation()
            .summary("Приветствие")
            .operationId("sayHello")
            .addParametersItem(new Parameter()
                .name("name")
                .in("query")
                .required(false)
                .schema(new StringSchema()))
            .responses(new ApiResponses()
                .addApiResponse("200", new ApiResponse()
                    .description("OK")
                    .content(new Content()
                        .addMediaType("text/plain", 
                            new MediaType().schema(new StringSchema())))))));

// Сериализация в JSON
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(openAPI);
System.out.println(json);

3. OpenAPI Generator (генерация кода по спецификации)

OpenAPI Generator — это инструмент, работающий в обратном направлении: по готовой OpenAPI-спецификации он генерирует клиентский или серверный код на Java и других языках. Поддерживает десятки шаблонов (Spring, Micronaut, JAX-RS и др.).

Пример генерации серверного кода через Maven-плагин

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.7.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>

После выполнения команды