Для чего нужна документация API
Что проверяют
Понимаете ли вы документацию как часть контракта сервиса, а не как вики, которую кто-то когда-то написал. Следом почти всегда спрашивают, чем вы её генерируете в Spring и как не дать ей разойтись с кодом.
Как отвечать
Начните с того, кому она нужна:
- потребители API: фронтенд, мобильная команда, соседние сервисы и партнёры узнают эндпоинты, параметры, форматы, коды ошибок и способ авторизации без переписки с вами;
- контракт: спецификация фиксирует, что считается ломающим изменением, и по ней договариваются о версиях;
- генерация кода: из OpenAPI-описания собираются клиенты и DTO на Java, TypeScript, Kotlin, это убирает ручную рутину и опечатки;
- тестирование: QA и контрактные тесты опираются на спецификацию, моки поднимаются прямо из неё.
Дальше про стек. Стандарт де-факто это OpenAPI (бывший Swagger). В Spring Boot 3 обычно берут springdoc-openapi: он строит спецификацию по контроллерам, отдаёт её на /v3/api-docs и поднимает рядом Swagger UI. Описания добавляют аннотациями @Operation, @ApiResponse, @Schema. Подходов два: code-first, когда спецификация генерируется из кода, и contract-first, когда сначала пишут YAML, а интерфейсы и модели генерирует openapi-generator-maven-plugin. Contract-first удобнее, если API согласуют несколько команд до начала разработки. Для асинхронных интерфейсов на Kafka есть AsyncAPI.
Хороший штрих: спецификацию проверяют в CI, сравнивая с предыдущей версией на ломающие изменения. Spring REST Docs строит документацию из тестов, и незадокументированное поле в ответе валит тест.
Где спотыкаются
Отвечают общими словами про «упрощение интеграции» и не называют ни одного инструмента. Для Java-разработчика это звучит так, будто документацию он видел только чужую.
Советуют Springfox. Он давно не развивается и со Spring Boot 3 не работает, актуальный выбор это springdoc.
Не описывают ошибки и безопасность: в спецификации есть только успешный 200, а форматы 400, 401, 409 и схема авторизации остаются для потребителя загадкой.