OpenAPI Diff

Что проверяет этот инструмент — и что «ломающее» означает на самом деле

Изменение является ломающим, когда клиент, корректно написанный против старой спецификации, может отказать против новой, не изменив ни строки собственного кода. Это определение определяет каждый вердикт на этой странице. Удаление пути или операции ломает, потому что существующим вызовам некуда идти. Удаление статуса ответа — прежде всего 2xx — ломает, потому что обработка ошибок клиента была написана вокруг старого набора. Добавление обязательного параметра или обязательного свойства запроса ломает, потому что вчерашний допустимый запрос внезапно отклоняется. Изменение типа или формата поля ломает, потому что парсеры, валидаторы и сгенерированные SDK строятся на объявленном типе. Удаление значения перечисления ломает, потому что клиент может по-прежнему отправлять его или хранить данные, которые больше не может интерпретировать. Всё остальное — новая конечная точка, необязательный параметр, новое поле ответа, новое значение перечисления, новый код статуса — сообщается как не ломающее: старые клиенты продолжают работать, даже если пока не могут использовать новую возможность.

Сравнение структурное, а не текстовое. Оба документа нормализуются в одну модель до всякого сравнения: каждый путь и операция, их параметры, индексированные по имени и расположению, тело запроса и каждый ответ, сведённые к сигнатуре схемы — детерминированной сводке типов, форматов, имён свойств, списков обязательных полей и значений перечислений, построенной рекурсивно и с разрешёнными локальными ссылками $ref. Поэтому перестановка ключей, переформатирование пробелов или переписывание каждого описания даёт пустой diff: ничто из этого не меняет контракт. И поэтому изменение, погребённое на три уровня вглубь ссылаемой схемы, тоже находится — сигнатура разворачивает ссылку, а не сравнивает её имя.

Принимаются две формы ввода, потому что экосистема публикует обе: сначала пробуется JSON, а когда это не удаётся, текст разбирается как YAML — формат, который использует большинство рукописных документов OpenAPI. Документы Swagger 2.0 тоже работают, включая их параметры in: body и схемы на каждый ответ. Намеренно нет ни живой загрузки, ни отправки на сервер: вставьте документы или перетащите файлы, точно как вы сделали бы это с захватом HAR, и сравнение выполняется при нажатии кнопки — а не при каждом нажатии клавиши —, поэтому две большие вставленные спецификации остаются отзывчивыми.

Используйте результат как ворота релиза, а не как украшение. На ревью список ломающих изменений — это повестка: каждая запись нуждается либо в исправлении, либо в повышении версии, либо в окне устаревания, либо в письменном решении, что разрыв намерен и объявлен. Список не ломающих изменений — это черновик журнала изменений. Экспорт diff в JSON позволяет архивировать это решение рядом с релизом, а копируемую сводку можно сразу вставить в запрос на слияние — та же дисциплина, что вы применили бы к изменению контракта вебхука, где молча изменённая полезная нагрузка ломает каждого подписчика разом.

Честные ограничения, сказанные прямо. Этот инструмент сравнивает объявленный контракт: он не может видеть поведение, которое спецификация не объявляет, — например поле, которое сохраняет тип, но меняет смысл, новое бизнес-правило, более строгие лимиты или сообщение об ошибке, которое клиенты (неразумно) разбирали. Он следует локальным ссылкам и сравнивает схемы до ограниченной глубины, поэтому патологически глубоко вложенные или взаимно рекурсивные схемы суммируются, а не разворачиваются бесконечно. И diff с нулём ломающих изменений — не обещание, что обновление безопасно: это свидетельство того, что задокументированный контракт выдержан, а именно такое свидетельство и стоит иметь перед развёртыванием.