OpenAPI Diff и проверка несовместимых изменений

OpenAPI Diff сравнивает базовую и новую спецификации API по смыслу, а не по тексту. Он сопоставляет операции по методу и пути (поэтому /users/{id} и /users/{userId} считаются одним эндпоинтом), разрешает внутренние ссылки $ref и сообщает о каждом изменении контракта с указанием операции, расположения, значений до и после и того, почему это важно для клиентов. Поддерживаются Swagger 2.0, OpenAPI 3.0 и OpenAPI 3.1 в формате JSON или YAML; Swagger 2.0 сначала приводится к структуре OpenAPI 3.

1. 1.Вставьте, загрузите или импортируйте базовую спецификацию (версию, которую клиенты используют сегодня).
2. 2.Добавьте новую спецификацию (предлагаемую версию).
3. 3.Нажмите «Сравнить».
4. 4.Просмотрите вкладки «Критичные», «Предупреждения» и «Совместимые» и отфильтруйте по методу или области.
5. 5.Выберите изменение, чтобы увидеть значения до и после и почему это важно.
6. 6.Скопируйте критичные изменения для pull request или скачайте отчёт Markdown или JSON для CI.

Запросы и ответы оцениваются в противоположных направлениях. Для запроса (то, что отправляют клиенты) критичным считается всё, что сужает принимаемое: новый обязательный параметр или свойство, удалённое значение enum, изменённый тип или формат, меньший максимум или больший минимум, новый шаблон или удалённый тип содержимого. Для ответа (то, что получают клиенты) критичным или предупреждением считается всё, что убирает или расширяет читаемое клиентами: удалённое свойство или успешный статус, изменённый тип, новое значение enum или обязательное свойство, ставшее необязательным. Удалённые эндпоинты, новая аутентификация, изменённые схемы безопасности и добавленные scope OAuth критичны. Правки описания, краткого описания, заголовка и примеров относятся к изменениям документации и скрыты, пока вы их не включите.

Сравнение выполняется в вашем браузере встроенным движком правил; спецификации никогда не загружаются на сервер. Импорт по URL получает файл напрямую из браузера без cookie, поэтому для серверов, блокирующих кросс-доменные запросы, файл нужно загрузить или вставить. Каждая спецификация может быть размером до 5 MB. Внешние файлы $ref выявляются, но не загружаются. Серверы, callbacks, webhooks, ссылки и расширения вендоров не сравниваются, а правила описывают вероятное влияние на клиентов, но не гарантируют его: строгий или нестрогий сервер может вести себя иначе.