Как перестать писать документацию к API руками и полюбить Swagger Core

Представь ситуацию: фронтенд-разработчик просит актуальную схему эндпоинта, а ты полчаса ищешь в коде, какие именно поля приходят в JSON и почему один из параметров вдруг стал обязательным. Если ты пишешь на Java и используешь JAX-RS, то наверняка знаешь про Swagger. Но часто мы воспринимаем его как некую магическую обертку, которая «просто генерирует страничку с кнопками». На самом деле за этим стоит swagger-core — движок, который превращает твой Java-код в стандарт OpenAPI.

Я периодически возвращаюсь к этому репозиторию, когда стандартные аннотации Spring или Quarkus начинают вести себя странно. Понимание того, как работает «ядро», помогает настраивать описание API гораздо гибче.

Что это за проект

swagger-core — это официальная Java-реализация спецификации OpenAPI. Если коротко: он берет ваши классы, модели и аннотации, а на выходе выдает JSON или YAML файл, который понимают все — от генераторов клиентского кода до тестировщиков.

Проект живет долго, и это видно по количеству веток. Сейчас основная работа идет в версии 2.2.x, которая полностью поддерживает OpenAPI 3.1. Если у вас старый проект на OpenAPI 2.0, придется сидеть на ветке 1.5, но лучше все-таки обновляться.

Поддержка Jakarta и переход с javax

Интересный момент, на который натыкаются многие при обновлении стека: начиная с версии 2.1.7, ребята добавили поддержку неймспейса Jakarta. В мире Java сейчас это главная точка боли — переход с javax.* на jakarta.*.

Разработчики swagger-core поступили мудро. Они не стали заставлять всех резко переходить на новый стандарт, а выпускают параллельный набор артефактов с суффиксом -jakarta. Если вы обновили сервер приложений до версии, где используется Jakarta EE 9+, просто добавьте суффикс к зависимостям, и все заработает.

Удобная работа с зависимостями через BOM

В больших проектах легко запутаться в версиях разных модулей Swagger: аннотации одной версии, модели другой, интеграция третьей. Чтобы не ловить MethodNotFoundException в рантайме, в репозитории предлагают использовать Bill of Materials (BOM).

В Maven это выглядит так:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-bom</artifactId>
      <version>2.2.49</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

После этого можно подключать нужные модули (например, swagger-jaxrs2 или swagger-annotations), не указывая версию вообще. BOM сам проследит, чтобы все части пазла подошли друг к другу. Кстати, плагины для Maven и Gradle в BOM специально не включили, чтобы не было конфликтов при сборке — их нужно прописывать отдельно.

Как это работает на практике

Проект поддерживает JAX-RS 2. Чтобы swagger-core «увидел» ваш API, достаточно расставить аннотации прямо над методами контроллеров.

@GET
@Path("/{username}")
@Operation(summary = "Получить пользователя по имени",
           responses = {
               @ApiResponse(description = "Объект пользователя",
                            content = @Content(mediaType = "application/json",
                            schema = @Schema(implementation = User.class))),
               @ApiResponse(responseCode = "404", description = "Пользователь не найден")
           })
public Response getUserByName(@PathParam("username") String username) {
    // логика
}

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

Кому стоит заглянуть в репозиторий

В первую очередь тем, кто хочет выжать максимум из OpenAPI 3.1. Эта версия спецификации принесла много полезного, например, улучшенную работу с webhooks и более гибкие схемы для JSON.

Если вы используете специфические фреймворки, которые не «подцепили» Swagger из коробки, в swagger-core есть модуль swagger-integration. Он позволяет настроить сканирование классов вручную. Это бывает полезно, если у вас сложная иерархия ресурсов или вы используете кастомные загрузчики классов.

В репозитории также лежат примеры интеграции с сервлетами. Если ваш проект на Java — это не очередной микросервис на Spring Boot, а суровый монолит на голых сервлетах, swagger-core поможет прикрутить документацию и туда.

swagger-core — это не тот инструмент, с которым играются на выходных. Это рабочая лошадка, которая берет на себя самую скучную часть работы разработчика.

Кому пригодится:

• Разработчикам на JAX-RS (Jersey, RestEasy).
• Тем, кто мигрирует на Jakarta EE.
• Архитекторам, которым нужно внедрить единый стандарт документации в компании.

Если вы до сих пор описываете API в Word или в комментариях к тикетам в Jira — самое время подключить swagger-core и забыть об этом как об ужасном сне. Живая документация, которую можно пощупать через Swagger UI, экономит часы общения между командами.