MoreLogin публикует машиночитаемую версию снимка контракта в info.version каждого документа OpenAPI. Версия использует календарный формат YYYY-MM-DD и обозначает контракт документации, а не сегмент версии в URL запроса.
| Изменение | Классификация | Отражение в документации |
|---|---|---|
| Добавление необязательного поля запроса или ответа, операции либо значения перечисления | Аддитивное | Записать в журнал изменений и обновить все локализованные спецификации |
| Уточнение описаний или исправление примера без изменения поведения во время выполнения | Исправление документации | Записывать, когда это меняет рекомендации по интеграции |
| Сделать необязательное поле обязательным, удалить или переименовать поле либо операцию, сузить допустимые значения, изменить сложившуюся семантику | Ломающее | До удаления предоставить путь миграции и отдельно версионированный контракт |
Пометить операцию как deprecated: true | Прекращение поддержки | Указать замену, дату объявления и планируемую дату удаления после её утверждения |
Клиентам следует игнорировать неизвестные поля ответа и значения перечислений там, где это допускает бизнес-логика. Это снижает поломки от аддитивных релизов.
Операция OpenAPI — авторитетное машиночитаемое место. Операция с прекращённой поддержкой должна содержать:
deprecated: true- описание с указанием замены или с прямым указанием, что замены нет
- запись-объявление в журнале изменений API
- планируемую дату удаления только после утверждения владельцами продукта и шлюза
Универсальный минимальный срок прекращения поддержки сейчас не гарантируется. Пока дата удаления не опубликована явно, клиентам следует считать операцию поддерживаемой, но планировать переход с неё.
Поведение во время выполнения остаётся авторитетным. OpenAPI, примеры, локализованные копии, манифест поведения операций и журнал изменений проверяются вместе в CI, чтобы не допустить расхождения контракта.
Успешная проверка качества репозитория подтверждает внутреннюю согласованность файлов OpenAPI, примеров, ссылок, локализованных копий и артефактов управления.
Проверка отображения страниц подтверждает, что выбранные маршруты документации загружаются и отображаются без клиентских ошибок.
Только авторизованный smoke-тест развёрнутого API может подтвердить соответствие производственного поведения опубликованному контракту. Репозиторий не запускает такой тест по умолчанию, поэтому в примечаниях к выпуску нужно отдельно указывать факт производственной проверки.