Как документировать API для фронтенда и интеграции и какие инструменты использовать

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

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

Как отвечать

• OpenAPI: стандарт описания REST API в YAML или JSON. Swagger это набор инструментов вокруг него: Swagger UI, Swagger Editor, генераторы;
• code-first в Spring Boot: springdoc-openapi строит спецификацию по контроллерам и отдаёт её на /v3/api-docs, а интерактивную страницу на /swagger-ui.html. Описания добавляют аннотациями @Operation, @Schema, @ApiResponse. Springfox с Spring Boot 3 не работает и не развивается;
• contract-first: сначала пишут спецификацию, из неё openapi-generator генерирует интерфейсы контроллеров и DTO на Java, а фронтенд получает типизированный клиент на TypeScript. Контракт согласуют до кода, и команды работают параллельно;
• ошибки: единый формат по RFC 9457 (Problem Details), в Spring 6 для него есть ProblemDetail. Коды ошибок описаны в спецификации вместе с примерами;
• события: для Kafka и других брокеров есть AsyncAPI, аналог OpenAPI для асинхронных интеграций;
• Spring REST Docs: собирает документацию из тестов, поэтому пример в ней гарантированно рабочий.

Чтобы документация не отставала, спецификацию проверяют в CI линтером и сравнением с прошлой версией на ломающие изменения, например утилитой oasdiff. Интеграторам дают Redoc как читаемую страницу, примеры запросов и changelog по версиям API.

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

Говорят «у нас есть Swagger» и считают вопрос закрытым. Спецификация без описаний полей, кодов ошибок и примеров сообщает только список эндпоинтов.

Считают Swagger и OpenAPI двумя названиями одного и того же, не отличая спецификацию от инструментов.

Открывают Swagger UI внутреннего сервиса наружу без авторизации. Для публичного API это нормально, для внутреннего это готовая карта для атаки.