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