Проверка контрактов 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) в любом из полей, чтобы сравнить немедленно, не дожидаясь паузы.