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

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

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

Как отвечать

Основа ответа: OpenAPI 3.x как единый контракт, из которого генерируется всё остальное. Дальше привяжите его к Python-стеку:

• FastAPI: схема строится из аннотаций и Pydantic-моделей, отдаётся на /openapi.json, интерактивная документация на /docs (Swagger UI) и /redoc. Качество зависит от вас: response_model, summary, tags, примеры в моделях и responses с описанием ошибок 401, 404, 422;
• Django REST Framework: drf-spectacular генерирует OpenAPI 3, аннотации через @extend_schema. Старый drf-yasg умеет только Swagger 2.0;
• Flask: flask-smorest или apispec с marshmallow-схемами;
• события и очереди: для Kafka, RabbitMQ и вебсокетов есть AsyncAPI, OpenAPI их не описывает.

Проговорите два подхода. Code-first: схема генерируется из кода, быстро и почти не расходится с реальностью. Design-first: сначала пишут YAML, согласуют с фронтендом, потом реализуют, это удобнее для внешних партнёров.

Затем процесс. Схема лежит в репозитории, в CI её проверяют линтером (spectral или redocly lint), сравнивают с версией из main через oasdiff на ломающие изменения и прогоняют schemathesis, который генерирует запросы по схеме и ловит расхождения с реальными ответами. Фронтенд получает типы через openapi-typescript или клиент через openapi-generator, и ошибка в контракте становится ошибкой компиляции у них. Коллекции Postman удобны для ручной проверки, но источником правды их лучше не делать.

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

Ведут документацию в вики руками. Через пару спринтов она расходится с кодом, и фронтенд перестаёт ей верить.

Описывают только успешный ответ. Формат ошибок, коды, авторизация и пагинация остаются за кадром, а именно на них интеграция и ломается.

Считают автогенерацию FastAPI готовой документацией. Без описаний полей, примеров и перечисления ошибок это просто список ручек.