Автор статьи: Сергей Прощаев @sproshchaev
Руководитель направления Java‑разработки в FinTech

В мире микросервисной архитектуры качественная документация API — это не роскошь, а необходимость. Она ускоряет интеграцию, снижает количество ошибок и упрощает жизнь как разработчикам, так и потребителям вашего сервиса. Исторически документация часто отставала от кода, но с появлением стандарта OpenAPI (ex‑Swagger) и его глубокой интеграции с экосистемой Spring этот процесс можно полностью автоматизировать.

В этой статье мы подробно рассмотрим, как профессионально подойти к документированию API, используя связку OpenAPI и Spring Boot. Чтобы материал был максимально практическим, мы создадим простой PersonService и на его примере покажем, как из кода генерируется всегда актуальная и интерактивная документация.

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

OpenAPI — это открытая спецификация для описания RESTful API. По сути, это язык, который позволяет в структурированном формате (YAML или JSON) описать все аспекты вашего API: эндпоинты, методы HTTP, параметры запроса, форматы тел запросов и ответов, модели данных, статус‑коды и даже требования к безопасности.

Использование OpenAPI решает несколько ключевых проблем:

1. Единый источник истины: документация генерируется прямо из кода, что исключает ее расхождение с реальностью.

2. Интерактивное тестирование: позволяет разработчикам сразу же опробовать API через веб‑интерфейс, не прибегая к Postman или curl.

3. Автогенерация кода: на основе OpenAPI‑спецификации можно автоматически генерировать клиентские SDK на разных языках, заглушки для сервера и многое другое.

Что такое SpringDoc OpenAPI?

SpringDoc — мост между Spring Boot и OpenAPI. SpringDoc — это библиотека с открытым исходным кодом, которая автоматически генерирует спецификацию OpenAPI 3.x из Spring‑приложения. Она интегрируется с такими фреймворками, как Spring MVC (Web), Spring WebFlux и Spring Boot.

Ключевое преимущество SpringDoc в его простоте. Достаточно добавить одну зависимость в ваш проект, и библиотека начнет сканировать ваши контроллеры, модели данных и конфигурации безопасности, чтобы построить точную спецификацию. На основе этой спецификации SpringDoc также предоставляет интерактивный UI Swagger, доступный по адресу /swagger‑ui.html.

Сравнение «ручного» подхода и автоматической генерации

Далее мы рассмотрим эти два варианта и обсудим плюсы и минусы использования каждого.

Сложность поддержки и актуальности

Ручное документирование требует от разработчика вести отдельный файл (например, openapi.yaml). Каждое изменение в коде — новый эндпоинт, изменение модели данных — должно быть вручную отражено в этом файле. Это создает постоянный риск расхождения, особенно в больших командах и на активных проектах. Процесс легко нарушить, забыв обновить документацию.

Автоматическая генерация с SpringDoc переносит burden описания API непосредственно в код. Документация становится побочным продуктом разработки. Если код изменился — изменилась и документация. Это значительно снижает операционные издержки и гарантирует, что документация всегда соответствует реализованному API.

Функциональность и удобство для потребителя

Статичный документ (PDF, Markdown) предоставляет только информацию для чтения. Разработчикам, которые хотят протестировать API, приходится вручную создавать запросы в сторонних инструментах, что замедляет процесс интеграции.

Интерактивный UI Swagger — это «играющая» документация. Потребитель API не только видит описание, но и может «выполнить» любой запрос прямо в браузере, передав необходимые заголовки и тело. Это убирает барьер для тестирования и делает API по‑настоящему discoverable.

Практический пример: Документируем Person Service

Для лучшего понимания рассмотрим, как выглядит процесс на практике. Создадим простой REST‑сервис для управления людьми, используя Lombok для минимизации шаблонного кода.

1. Подключение зависимостей

Добавляем SpringDoc и Lombok в pom.xml:

<dependencies>
    <!-- SpringDoc OpenAPI -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.3.0</version>
    </dependency>
    
    <!-- Lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

После этого по умолчанию UI Swagger будет доступен по адресу http://localhost:8080/swagger‑ui.html.

2. Создание модели и контроллера с аннотациями OpenAPI и Lombok

Теперь создадим модель Person и контроллер, обогатив их аннотациями для более детального описания. Lombok позволит нам избавиться от шаблонных геттеров, сеттеров и конструкторов.

Модель данных с Lombok:

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "Модель данных человека")
public class Person {
    
    @Schema(description = "Уникальный идентификатор человека", 
            example = "123")
    private Long id;
    
    @Schema(description = "Имя человека", 
            example = "Иван", 
            requiredMode = Schema.RequiredMode.REQUIRED)
    private String firstName;
    
    @Schema(description = "Фамилия человека", 
            example = "Иванов", 
            requiredMode = Schema.RequiredMode.REQUIRED)
    private String lastName;
    
    @Schema(description = "Возраст человека", 
            example = "30", 
            minimum = "0", maximum = "150")
    private Integer age;
}

Аннотации Lombok делают код исключительно чистым:

• @Data генерирует геттеры, сеттеры, toString, equals и hashCode

• @NoArgsConstructor создает пустой конструктор

• @AllArgsConstructor создает конструктор со всеми полями

Теперь напишем простой REST‑контроллер:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.Parameter;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;

@RestController
@RequestMapping("/api/persons")
@Tag(name = "Person API", 
description = "API для управления данными о людях")
@RequiredArgsConstructor
public class PersonController {

    private final Map<Long, Person> personStore 
                              = new ConcurrentHashMap<>();
    private final AtomicLong idCounter = new AtomicLong();

    @Operation(
        summary = "Получить человека по ID",
        description = "Возвращает объект человека, если он найден в системе."
    )
    @ApiResponse(responseCode = "200", description = "Человек найден")
    @ApiResponse(responseCode = "404", description = "Человек не найден")
    @GetMapping("/{id}")
    public ResponseEntity<Person> getPerson(@Parameter(description = "ID человека") @PathVariable Long id) {
        Person person = personStore.get(id);
        return person != null ? ResponseEntity.ok(person) : ResponseEntity.notFound().build();
    }

    @Operation(summary = "Создать нового человека")
    @ApiResponse(responseCode = "201", description = "Человек успешно создан")
    @PostMapping
    public ResponseEntity<Person> createPerson(@RequestBody Person person) {
        person.setId(idCounter.incrementAndGet());
        personStore.put(person.getId(), person);
        return ResponseEntity.status(HttpStatus.CREATED).body(person);
    }
}

3. Результат: Интерактивная документация

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

* На главной странице будет отображен тег «Person API» с нашим описанием.

* Раскрыв эндпоинт GET /api/persons/{id}, мы увидим его описание, параметр id и возможные коды ответов.

* Нажав кнопку «Try it out», можно ввести значение ID и выполнить реальный запрос к нашему сервису.

* В разделе «Schemas» будут отображены модели данных, в том числе наша Person с примерами значений и описаниями полей.

Все достаточно компактно и интуитивно понятно и при этом любые изменения к коде автоматически обновляют документацию.

Рекомендации по документированию

При внедрении OpenAPI в ваш проект важно следовать нескольким принципам:

1. Документируйте прямо в процессе разработки — добавляйте аннотации сразу при создании контроллера или модели. Это становится привычкой, как написание тестов.

2. Используйте описательные примеры — так например поле example в аннотациях является мощным инструментом, который показывает потребителю API, какие данные стоит ожидать.

3. Не пренебрегайте описанием ошибок — создавайте стандартные модели для ошибок. Примером этого может служить ApiErrorResponse в котором можно документировать состав ошибок, которые может возвращать каждый эндпоинт (4xx, 5xx).

4. Настройте конфигурацию — используйте бин OpenAPI в конфигурации Spring, чтобы добавить общую информацию об API. Это может быть название, версия и контакты. 

Пример такого бин OpenAPI в конфигурации Spring:

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Person Service API")
                        .version("1.0")
                        .description("Документация для микросервиса")
                        .contact(new Contact()
                            .name("Команда разработки")
                            .email("dev@example.com")));
    }
}

Полный код примера доступен в репозитории GitHub по ссылке 

Заключение

Выбор между ручным ведением документации и автоматической генерацией с помощью OpenAPI и SpringDoc — это выбор между прошлым и будущим разработки API. Ручной подход может казаться простым на старте, но с ростом проекта он неизбежно приводит к устаревшей и ненадежной документации.

Связка SpringDoc OpenAPI, Spring Boot предоставляет элегантное, мощное и практически бесплатное решение для создания всегда актуальной, интерактивной и полезной документации. 

SpringDoc автоматически превращает этот код в качественную документацию. Это инвестиция в качество вашего продукта и в производительность команд, которые с ним работают. Начиная новый проект, сразу закладывайте эту практику в его основу — и ваши потребители скажут вам «спасибо».

Если вам близка тема архитектуры и практики построения современных приложений, стоит глубже взглянуть на сам фреймворк. На курсе «Разработчик на Spring Framework» разбирают реальные кейсы продакшн-разработки и учат работать со Spring Boot, MVC, Security и Reactive Stack — так, как это делают в коммерческих командах. Чтобы узнать, подойдет ли вам программа курса, пройдите вступительный тест.

А чтобы узнать больше о формате обучения и познакомиться с преподавателями, приходите на бесплатные демо-уроки:

• 12 ноября: «OpenAPI + Spring». Записаться

• 24 ноября: «Неожиданное введение в Spring MVC». Записаться