OpenAPI: сделать контракт источником истины, а не доками

За следующие пятнадцать минут ты увидишь, почему спека без enforcement — это замедленная мина, и какие три шага в пайплайне её обезвреживают до того, как сломается хоть один клиент.

Спека — это контракт, иначе фикция

OpenAPI — это машиночитаемое описание твоего HTTP API: каждый путь, форма каждого запроса и ответа, каждый статус-код, каждая схема авторизации, записанные в YAML или JSON. Столько у большинства команд есть. Вопрос, который решает, помогает оно или вредит, лежит на уровень глубже: спека — это источник истины или описание истины, записанное где-то ещё?

Когда спека — побочный документ (написали один раз, выгрузили на портал доков, никогда не сверяли с работающим сервисом), она гниёт за месяцы. Код меняется, спека — нет, и теперь у тебя два контракта: тот, что сервер обеспечивает, и тот, что заявляет спека. Клиенты интегрируются по спеке, спека — фикция, и интеграция падает в проде. Это contract drift (молчаливое расхождение спеки и реализации), и это исход по умолчанию, пока что-то активно ему не мешает.

Фикс — не «писать доки лучше». Фикс — сделать спеку несущей: код генерируется из неё, запросы валидируются по ней, а её дифф гейтит каждый pull request. Контракт, который нельзя нарушить без падения билда, — это контракт. Всё остальное — страница в вики.

Spec-first vs code-first: где живёт истина

Спроси себя: контракт твоего API ревьюят до того, как написана первая строка хендлера, или он рождается из того, что инженер решил написать в пятницу? От ответа зависит, какую модель выбирать.

Получить спеку можно двумя способами, и разница в том, какой артефакт авторитетен.

Spec-first (design-first — «спека раньше кода»): ты пишешь OpenAPI-документ руками, ревьюишь его как дизайн API и генерируешь серверные заглушки, типизированных клиентов и моки из него. Спека — источник истины; код ей соответствует. Фронтенд может строить против сгенерированного мока в тот же день, когда бэкенд только начал, потому что контракт существует раньше любой реализации.

Code-first («сначала код»): ты пишешь сервер с аннотациями или декораторами (@ApiProperty, type hints в FastAPI, springdoc), а инструмент генерирует спеку из работающего кода. Код — источник истины; спека — его отражение. Меньше церемоний, и спека не разойдётся с хендлером, из которого её извлекли, — но может разойтись с тем, чего ждали потребители, потому что никто не отревьюил контракт как контракт до выкатки.

Ни то ни другое не ошибка. Решение сеньора такое: spec-first, когда API потребляют несколько команд или внешние партнёры и контракт нужно ревьюить и держать стабильным; code-first, когда одна команда владеет обоими концами и скорость важнее предварительного дизайна. Что не опционально в любой модели — это enforcement: спека должна валидироваться и диффиться, как бы она ни родилась.

Что реально даёт OpenAPI 3.1

Спека отрабатывает не самим документом, а тулингом, который открывает. Важны четыре выигрыша:

• Сгенерированные типизированные клиенты и серверные заглушки. Прогони генератор по спеке и получи SDK на TypeScript, Go, Swift, Kotlin — с методами, моделями, типами ошибок. Класс интеграционных багов («я слал userId, серверу нужен user_id») исчезает, потому что запрос больше никто не пишет руками. Команды, выкатывающие публичные API, генерируют SDK из спеки именно чтобы убить эту категорию целиком.
• Валидация запросов на edge. Middleware валидирует входящие запросы по спеке до того, как они дойдут до хендлера. Битое тело отклоняется точным 400 с именем виноватого поля, а твоя бизнес-логика мусора не видит.
• Доки, которые не разойдутся молча. Когда отрендеренные доки генерируются из той же спеки, что гейтит CI, «доки врут» перестаёт быть возможным — доки и есть контракт.
• Мок-серверы. Инструмент отдаёт фейковые ответы прямо из примеров спеки, и потребители интегрируются раньше, чем появился бэкенд.

Вместе эти четыре выигрыша означают: спека отрабатывает не как документ, а как цепочка инструментов. Без CI-гейта первые три есть на бумаге, но ничто не останавливает ломающее изменение.

Конкретно OpenAPI 3.1 выравнивает язык схем с JSON Schema 2020-12, так что твои ключевые слова валидации — это настоящий JSON Schema, а не подмножество эпохи 3.0. Цена этой мощи: nullable: true больше нет — теперь пишешь type: ["string", "null"] — а exclusiveMinimum/exclusiveMaximum принимают число, а не булево. 3.1 ещё добавляет верхнеуровневый webhooks для документирования событий, которые твой API шлёт, а не только принимает. Многие инструменты по-прежнему дефолтят в 3.0, так что проверь поддержку генератора до апгрейда.

Детект ломающих изменений: гейт, который ловит пятничный деплой

Когда видишь PR, который трогает имя поля, тип или массив required, легко пропустить, стало оно required или нет — одно слово, а ломает каждого клиента, кто его не шлёт. У истории с tenantId один чистый фикс: инструмент, который диффит новую спеку против предыдущей версии и роняет PR на ломающем изменении. oasdiff (утилита для diff-анализа OpenAPI-спек) — частый выбор: он классифицирует 450+ категорий изменений и знает, какие ломающие. Добавление required-поля запроса, удаление поля ответа, которое клиент может читать, сужение типа, удаление значения enum, удаление эндпоинта — всё ломающее, всё ловится до мержа.

Вшитый в CI, чек туп и эффективен: пайплайн диффит спеку из PR против main, и если появляется ломающее изменение, билд красный, а инженер видит ровно какое поле сломалось — раньше любого клиента. Пятничный деплой не доходит до прода, потому что контракт обеспечивается тем же гейтом, что и тесты. Тонкость в 3.1: так как nullability переехала в массив типов, удаление "null" из type: ["string", "null"] регистрируется как смена типа, а не как смена nullable — дифф всё равно ловит это, просто по другому правилу, поэтому смотри на категорию, которую сообщает инструмент, а не только на количество.