Как организована работа с новыми API, используются ли Swagger или другие инструменты?

Что проверяют

Есть ли у вас процесс вокруг контракта API: кто его пишет, где он живёт, как фронтенд и соседние сервисы узнают об изменениях. Следом спрашивают, как вы ловите ломающие изменения до релиза и что используете, кроме Swagger UI.

Как отвечать

Сначала уточните термины: OpenAPI это спецификация, а Swagger это набор инструментов вокруг неё (UI, Editor, Codegen). Дальше назовите подход и инструменты под Spring:

• code-first: контракт генерируется из контроллеров библиотекой springdoc-openapi, аннотации @Operation, @Schema, @ApiResponse уточняют описание. Спецификация отдаётся по /v3/api-docs, интерфейс по /swagger-ui.html. Быстро стартовать, но документ хорош ровно настолько, насколько аккуратны аннотации;
• API-first: YAML со спецификацией пишется до кода и проходит ревью в PR, openapi-generator-maven-plugin генерирует интерфейсы контроллеров и DTO, фронтенд из того же файла получает TypeScript-клиент. Команды работают параллельно, фронтенд живёт на моках (Prism, WireMock);
• защита от поломок: в CI сравнение новой спецификации со старой (oasdiff или openapi-diff), контрактные тесты через Spring Cloud Contract или Pact;
• версионирование: ломающее изменение идёт через новую версию (/v2) и срок жизни старой, поле сначала помечается deprecated;
• смежные инструменты: Postman или Bruno для ручных проверок, AsyncAPI для событий в Kafka, protobuf для gRPC.

Если этот вопрос задаёте вы работодателю, хорошие признаки ответа: спецификация лежит в репозитории, её меняют через ревью, фронтенд генерирует клиент. Тревожный: «документация в Confluence, обновляем по возможности».

Где спотыкаются

Называют springfox. Он давно не развивается и не работает со Spring Boot 3, актуальный вариант springdoc-openapi.

Оставляют Swagger UI открытым на проде без авторизации. Внутренние эндпоинты видны всем, отключается это в профиле прода через springdoc.swagger-ui.enabled=false и springdoc.api-docs.enabled=false.

Рассказывают только про генерацию документации. Интервьюеру важнее, как изменения контракта согласуются и проверяются, а красивая страница с эндпоинтами это лишь побочный эффект.