Вики врёт, прод молчит: почему пора сделать OpenAPI единственным источником правды о вашем API

Вот важная новость с фронта ИИ: Я мобильный разработчик. Иногда при работе со структурами данных я имею дело с endpoint-ами, иду в вики, нахожу страницу с описанием — и не верю ей. Потому что по опыту знаю: страница описывает API таким, каким он был задуман полгода назад, а не таким, какой он сейчас.

Дальше начинается знакомый ритуал: пишу в чат бэкендеру, он отвечает «глянь в сваггере», сваггер сгенерирован из аннотаций и показывает приблизительную картину, реальный ответ с сервера от неё отличается, потому что правило сериализации живёт в одном месте, а правило генерации описания — в другом. В итоге я делаю то, что делает большинство клиентских разработчиков: дёргаю endpoint «вживую», смотрю реальный JSON и верю только ему. То же самое бывает и при работе с внешними API (в том числе и солидных компаний).

Технические детали

Это и есть проблема источника правды. У нас не один источник, а несколько, и они конкурируют. Вики — это намерение.

Код бэкенда — это реализация. Реальный трафик — это факт. И когда между ними возникает расхождение (а оно возникает всегда), цена ошибки ложится в первую очередь на потребителя API: на фронтенд, на iOS, на Android, на десктоп, на внешних интеграторов.

Эту боль на Habr описывали многие. Алексей, Java-разработчик ЮMoney, в статье «Как улучшить межсерверное взаимодействие и сэкономить время разработчика» формулирует её предельно прямо: «Swagger UI, который генерируется автоматом по метаданным классов, показывает очень примерное описание того, что у нас реально отдаётся из API. Поэтому фронты и мобильные разработчики не могут начать разработку, не вызвав endpoint на живую».

Это не чья-то личная неаккуратность — это структурный изъян процесса, в котором правда не централизована.

Событие, по словам экспертов, усилит конкуренцию в сфере ИИ.