Перевірка контрактів API

Ви вставляєте (або завантажуєте) базову (стару) та нову (revision) специфікацію OpenAPI 3.x, інструмент проходить кожен шлях, параметр, тіло запиту, відповідь, вимогу безпеки та схему в обох версіях і повідомляє, що змінилося: додані чи видалені ендпоінти, зміни обов'язковості параметрів і полів запиту, звуження типів або enum, зниклі поля відповіді чи коди статусу, зміни вимог безпеки та зміни композиції allOf/oneOf/anyOf.

Усе, що може порушити роботу наявного клієнта: видалений ендпоінт, параметр або поле запиту, що стало обов'язковим, видалене поле чи код статусу відповіді, поле, яке більше не гарантується у відповіді, або тип/enum, що став вужчим (включно з масивами nullable-типів OpenAPI 3.1, наприклад видалення "null" з `["string", "null"]`). Нові ендпоінти, нові необов'язкові поля та нові поля відповіді є адитивними й показуються окремо як безпечні.

Так. Додані/видалені вимоги безпеки (глобальні та для окремих операцій), зміни визначень схем безпеки (наприклад, перенесення API-ключа із заголовка в query-параметр), нещодавно позначені як deprecated операції та зміни server URL — усе це подається як інформаційні знахідки, а не breaking чи safe, оскільки (відповідно до того, як ці перевірки за замовчуванням класифікує сам oasdiff) жоден напрямок не є універсально правильним чи неправильним; ви самі вирішуєте, чи важливо це для вашого API.

Так. Члени `allOf` розв'язуються та об'єднуються перед порівнянням, тому обов'язкове поле, додане глибоко всередині складеної схеми, все одно буде виявлене. Набори варіантів `oneOf`/`anyOf` порівнюються й позначаються як інформаційні при додаванні чи видаленні варіанта, оскільки те, чи є конкретна зміна breaking, залежить від того, як ваші клієнти розрізняють варіанти.

Ні — порівнюються лише специфікації OpenAPI 3.x. Swagger 2.0 (старіший формат) описує параметри й тіла запитів інакше, тому застосування тих самих правил дало б хибні результати. Під час вставлення документа Swagger 2.0 замість тихого хибного diff з'явиться зрозуміла помилка.

Ні. І розбір, і порівняння виконуються у вашому браузері — специфікація ніколи не залишає ваш пристрій, на відміну від більшості інших інструментів порівняння OpenAPI, які обробляють завантажений файл на своєму сервері, навіть якщо стверджують, що не зберігають його. Це стосується й завантаження/перетягування файлу: файл читається локально й ніколи не передається.

Він порівнює тіла запитів і відповідей `application/json`, що охоплює переважну більшість REST API, але не оцінює інші типи вмісту, заголовки відповідей, описи чи приклади. `$ref`, що вказує за межі документа (на окремий файл чи URL), позначається як нерозв'язний, а не тихо пропускається.

Так, і те, і інше. Кожне поле приймає JSON або YAML незалежно й визначає, який із них ви використали, тож можна порівнювати базову специфікацію в JSON із новою версією в YAML або навпаки. Також можна перетягнути файл .json/.yaml/.yml на будь-яке поле або скористатися кнопкою Upload file — файл читається в браузері й ніколи нікуди не завантажується.

Інструмент працює з будь-яким документом, що має поле "openapi": "3.x" та об'єкт "paths", що охоплює і 3.0, і 3.1 — включно з формою масиву для `type` у 3.1 (наприклад, `["string", "null"]`) — і відхиляє лише документи, схожі на Swagger 2.0.

Підтримуються Text (.txt), Markdown (.md) та JSON (.json) — оберіть потрібний формат у випадному списку поруч із Download report перед завантаженням. Експорт у JSON включає повний список знахідок і лічильники за рівнями серйозності, тож його можна передати в інший скрипт (наприклад, CI-перевірку), якщо це потрібно.

Працює і так, і так: натисніть Compare для миттєвого перезапуску або просто продовжуйте вводити текст — після короткої паузи порівняння виконається автоматично. Також можна натиснути Ctrl+Enter (Cmd+Enter на Mac) у будь-якому з полів, щоб порівняти негайно, не чекаючи на паузу.