01
Не перепутайте версии
Оценка делается для клиентов старого контракта. Обмен входов сначала показывает предпросмотр; после применения можно один раз вернуть входы и прежний результат.
Контракты API
сравнение спецификаций OpenAPIПроверка перед выпуском
Вставьте старую и новую версии отдельно, затем запустите сравнение.
сравнение спецификаций OpenAPI
Старая спецификация
Новая спецификация
Отчёт об изменениях
Обе спецификации обрабатываются в браузере; запросы к API не отправляются.
Параметры сравнения
Область: операции, параметры, тела запросов и ответы. Статический отчёт не доказывает совместимость сервера.
Вставьте обе спецификации для сравнения.
Сравнение спецификаций OpenAPI нужно перед выпуском версии, если клиенты уже используют прежний контракт. Построчный diff не объясняет, сломает ли их удалённый маршрут или новый обязательный параметр.
Этот OpenAPI diff группирует изменения по влиянию на потребителя. Ломающие изменения API видны отдельно, а неопределённые случаи остаются на ручную проверку обратной совместимости API.
Зачем нужно сравнение спецификаций OpenAPI
Оценка от старого контракта к новому
Сравнение спецификаций OpenAPI учитывает направление изменений. Удалённое поле ответа и новый маршрут попадают в разные категории, поэтому опасные изменения видны первыми.
Явные исключения в отчёте
Точно указанный путь исключается с обеих сторон и перечисляется в итоговом отчёте. Проверяющий видит, какие операции сознательно не анализировались.
Три решения перед анализом
02
Укажите путь целиком
Пишите ключ OpenAPI path, например /internal/health, по одному в строке. Это не регулярное выражение и не JSON Pointer; изменение списка делает отчёт устаревшим.
03
Фильтр не меняет файл отчёта
Категория ограничивает только видимый список. Экспорт JSON и Markdown сохраняет все свежие находки и исключённые пути.
Какие элементы контракта проверяются
Маршруты и методы
Удалённая операция отмечается как потенциальный разрыв, новая — отдельно. Так сравнить схемы OpenAPI проще, чем искать смысл среди строк текста.
Параметры и ответы
Отслеживаются новые обязательные параметры и поля запроса, исчезнувшие коды ответа и свойства ответа. Простые изменения типов и enum проверяются при разрешимых локальных ссылках.
Проверяемый отчёт
Каждая запись содержит метод, путь, правило и значения до/после. Полный файл доступен только после успешного анализа обеих спецификаций.
Границы статического вывода
- Без запросов по URL
- Обрабатываются только вставленные JSON или YAML. Инструмент не загружает спецификацию из сети и не вызывает работающий API.
- Исключения только по точному пути
- Шаблоны, регулярные выражения и маршруты callback не поддерживаются. Переименование пути выглядит как удаление и добавление.
- Неполные ссылки блокируют отчёт
- Внешний $ref, неподдерживаемый диалект, webhook или callback не позволяют выдать полный отчёт о рисках.
- Не доказательство поведения сервера
- Статическая схема не знает фактическое поведение API и всех SDK. Для релиза нужны тесты существующих клиентов. Обратная совместимость API остаётся вопросом для тестов потребителей.
Вопросы про сравнение спецификаций OpenAPI
Какие форматы схем поддерживаются?
Поддерживаются Swagger 2.0 и OpenAPI 3.0/3.1 в JSON или YAML. Для полноценного анализа нужны два самостоятельных документа без внешних ссылок.
Что считается ломающим изменением (breaking change)?
Это изменение, после которого запрос, допустимый по старому контракту, может перестать работать: удалённая операция, обязательный новый параметр или исчезнувший ожидаемый ответ.
Можно ли отключить анализ влияния?
Нет. Анализ влияния включён в сам отчёт; можно лишь отфильтровать видимые категории. Без риска обычный diff скрывал бы важный смысл изменений.
Как инструмент определяет тип схемы?
Формат определяется по содержимому вставленного текста. При ошибке парсинга отображаются сторона документа и доступная позиция строки и столбца.
В каком формате выдается результат?
Сравнение спецификаций OpenAPI выдаёт структурированный JSON и Markdown. В записи есть категория, правило, метод, путь и значения до и после изменения.
Сравнение было полезным?
Начните сравнение спецификаций OpenAPI
Сравнение спецификаций OpenAPI даёт проверяемый список рисков, но требует тестов потребителей перед публикацией.