Используете ли автодокументирование API, например Swagger

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

Понимаете ли вы, откуда берётся документация и насколько ей можно верить. Следом обычно спрашивают, чем Swagger отличается от OpenAPI и как вы следите, чтобы изменения API не ломали клиентов.

Как отвечать

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

Дальше про стек, в котором вы работали:

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

Подход code-first удобен, пока API пользуется ваша же команда. Когда контракт согласуют с внешними командами, чаще выбирают design-first: сначала пишут YAML, по нему генерируют заглушки и клиентов через openapi-generator.

Добавьте, как схема помогает качеству: её выгружают в CI и сравнивают с предыдущей версией, чтобы ловить ломающие изменения (например, oasdiff), а schemathesis генерирует по схеме тесты и находит ответы, которые ей не соответствуют.

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

Считают, что автодокументация всегда актуальна. Она описывает только то, что выражено типами: хендлер, который возвращает dict без response_model, выглядит в схеме как пустой объект, а ошибки 4xx не видны вовсе.

Путают Swagger и OpenAPI или говорят о Swagger как о библиотеке, которую «подключили в проект».

Оставляют /docs открытым на проде вместе с внутренними эндпоинтами. Его закрывают авторизацией или отключают через docs_url=None и openapi_url=None.