JSON Schema для надійних контрактів API
Робочий процес зі схемою, у якому правильні та помилкові дані запитів стають виконуваною документацією.
Правильний синтаксис JSON доводить лише можливість розбору документа. Контракт має описувати структури й значення
на які можуть покладатися клієнти.
Явно моделюйте відсутність і null
Обов’язкове
необов’язкове та nullable-поле — різні стани. Визначте типи
елементи масивів
переліки
формати
межі та правило additionalProperties.
Перевіряйте помилкові приклади
Додайте приклади з відсутніми полями
хибними типами
невідомими значеннями переліку
зайвими властивостями
порожніми масивами та кожною гілкою oneOf або anyOf.
Керуйте змінами контракту
Порівнюйте схеми й реальні дані запитів між випусками
відділяйте сумісні доповнення від несумісних змін і перевіряйте згенеровані клієнтські типи вручну.
Чекліст схеми API
- Визначте обов’язкові необов’язкові та nullable-поля
- Свідомо обмежте масиви переліки й формати
- Додайте показові помилкові приклади
- Перевірте перетини oneOf та anyOf
- Тестуйте зміни на реальних даних
Пов’язані гайди
Дізнайся workflow за цим інструментом і що перевіряти далі.
Як покроково налагоджувати JSON-відповідь API
Послідовний процес, що відокремлює транспортні помилки, синтаксис JSON і невідповідність контракту даних.
Як дебажити JSON API payloads
Практичний workflow для форматування JSON, пошуку syntax errors, перевірки payload shape і response status, коли API data виглядає неправильно.