Категории

← View All Tools

Детектор ломающих изменений OpenAPI diff

Сравнивает схемы OpenAPI или GraphQL, помечает ломающие изменения и формирует отчет о влиянии для API-команд

Примеры результатов

2 Примеры

Найти удаленное поле ответа до релиза

Сравнивает две версии OpenAPI и помечает свойство, исчезнувшее из ответа 200

{
  "releaseRisk": "high",
  "summary": {
    "breakingChanges": 1
  },
  "changes": [
    {
      "path": "GET /users/{id} -> response 200.email",
      "summary": "Response field removed"
    }
  ]
}
Показать параметры ввода
{ "oldSchema": "openapi: 3.0.0\npaths:\n /users/{id}:\n get:\n responses:\n \"200\":\n description: ok\n content:\n application/json:\n schema:\n type: object\n properties:\n id: { type: string }\n email: { type: string }\n", "newSchema": "openapi: 3.0.0\npaths:\n /users/{id}:\n get:\n responses:\n \"200\":\n description: ok\n content:\n application/json:\n schema:\n type: object\n properties:\n id: { type: string }\n", "schemaType": "openapi", "includeImpactAnalysis": true }

Проверить изменение входного контракта GraphQL

Определяет новый обязательный field в input-объекте, чтобы команды обновили мутации до выката

{
  "schemaType": "graphql",
  "summary": {
    "totalChanges": 1,
    "breakingChanges": 1,
    "dangerousChanges": 0,
    "nonBreakingChanges": 0
  },
  "impactedAreas": [
    "field"
  ],
  "releaseRisk": "high",
  "changes": [
    {
      "severity": "breaking",
      "area": "field",
      "path": "input:CreatePostInput.category",
      "summary": "Required input field added",
      "impact": "Mutations or queries sending this input object must populate the new required field."
    }
  ]
}
Показать параметры ввода
{ "oldSchema": "input CreatePostInput { title: String! }\ntype Mutation { createPost(input: CreatePostInput!): String! }", "newSchema": "input CreatePostInput { title: String!, category: String! }\ntype Mutation { createPost(input: CreatePostInput!): String! }", "schemaType": "graphql", "includeImpactAnalysis": true }

Ключевые факты

Категория
Development
Типы входных данных
textarea, select, text, checkbox
Тип результата
json
Покрытие примерами
4
API доступен
Yes

Обзор

Детектор ломающих изменений OpenAPI diff — это специализированный инструмент для автоматического сравнения схем OpenAPI и GraphQL. Он анализирует старую и новую версии API, выявляет несовместимые (breaking) изменения и формирует подробный JSON-отчет об их влиянии. Это помогает командам разработчиков и архитекторам предотвращать поломки на стороне клиентов, оценивать риски перед релизом и поддерживать строгую обратную совместимость контрактов.

Когда использовать

  • •Перед слиянием (merge) изменений в основную ветку для проверки обратной совместимости API.
  • •При обновлении контрактов между микросервисами для предотвращения сбоев интеграции.
  • •Во время ревью изменений GraphQL-схем, чтобы убедиться в отсутствии удаленных полей или новых обязательных параметров.

Как это работает

  • •Вставьте текущую (старую) версию схемы OpenAPI (YAML/JSON) или GraphQL SDL в первое текстовое поле.
  • •Добавьте обновленную (новую) версию схемы во второе поле.
  • •Выберите тип схемы (OpenAPI или GraphQL) или оставьте автоматическое определение, а также включите опцию анализа влияния.
  • •Инструмент сравнит обе схемы и сгенерирует JSON-отчет с указанием уровня риска релиза и списком всех ломающих изменений.

Сценарии использования

Проверка pull request'ов на наличие изменений, которые могут сломать мобильные или веб-клиенты.
Генерация отчетов о рисках релиза для QA-инженеров и менеджеров продукта.
Аудит эволюции публичного API для составления корректного changelog'а для внешних разработчиков.

Примеры

1. Поиск удаленного поля в ответе API

Backend-разработчик
Контекст
Команда рефакторит сервис профилей пользователей и случайно удаляет поле email из ответа эндпоинта.
Проблема
Нужно убедиться, что изменения в OpenAPI-спецификации не сломают текущих клиентов, ожидающих это поле.
Как использовать
Вставьте старую YAML-схему с полем email и новую схему без него, выберите тип OpenAPI и включите анализ влияния.
Пример конфигурации
schemaType: openapi, includeImpactAnalysis: true
Результат
Инструмент помечает удаление поля как высокий риск (high release risk) и указывает точный путь: GET /users/{id} -> response 200.email.

2. Проверка новых обязательных полей в мутации

API-архитектор
Контекст
При развитии GraphQL API в input-объект CreatePostInput добавляется новое поле category.
Проблема
Выявить, сделано ли новое поле обязательным, что приведет к ошибкам валидации у старых клиентов.
Как использовать
Вставьте старый GraphQL SDL и новый SDL с полем category: String!, выберите тип GraphQL.
Пример конфигурации
schemaType: graphql, includeImpactAnalysis: true
Результат
Отчет показывает ломающее изменение (breaking change) из-за добавления обязательного поля ввода, предупреждая, что все клиентские мутации должны быть обновлены.

Проверить на примерах

development
Примеры OpenAPI/Swagger
Комплексные примеры документации API с использованием OpenAPI 3.0 и спецификаций Swagger для RESTful сервисов
title token openapi
sample
Примеры OpenAPI/Swagger
Примеры спецификации OpenAPI/Swagger для документации REST API и определения контрактов
title token openapi
sample
Примеры Mock Service Worker
Комплексные примеры MSW (Mock Service Worker), включая мокирование API, GraphQL, WebSocket и продвинутые паттерны обработки запросов
keywords graphql,api
sample
Примеры Apache Pulsar
Примеры Apache Pulsar включая pub/sub, ридеры, потребители с разными типами подписок, управление схемами и многоуровневое хранилище для корпоративной обмена сообщениями
keywords diff,schema
sample

Связанные хабы

Инструменты Json для Generate
Изучите 33 инструментов json для сценариев generate и быстро сравните близкие утилиты.
Инструменты Design для Generate
Изучите 19 инструментов design для сценариев generate и быстро сравните близкие утилиты.
Инструменты Pdf для Generate
Изучите 10 инструментов pdf для сценариев generate и быстро сравните близкие утилиты.
Инструменты Audio для Generate
Изучите 8 инструментов audio для сценариев generate и быстро сравните близкие утилиты.

FAQ

Какие форматы схем поддерживаются?

Инструмент поддерживает схемы OpenAPI (Swagger) в форматах YAML и JSON, а также схемы GraphQL SDL.

Что считается ломающим изменением (breaking change)?

К ломающим изменениям относятся: удаление существующих полей ответа, добавление новых обязательных параметров запроса, изменение типов данных или удаление эндпоинтов.

Можно ли отключить анализ влияния?

Да, вы можете снять галочку «Добавить анализ влияния», если вам нужен только базовый список отличий без оценки рисков для клиентов.

Как инструмент определяет тип схемы?

По умолчанию используется автоопределение на основе синтаксиса (auto detect), но вы можете вручную выбрать OpenAPI или GraphQL в настройках.

В каком формате выдается результат?

Результат предоставляется в структурированном формате JSON, который содержит сводку изменений, пути к измененным элементам и уровень риска.

Документация API

Конечная точка запроса

POST /ru/api/tools/openapi-diff-breach-detector

Параметры запроса

Имя параметра Тип Обязательно Описание
oldSchema textarea Да -
newSchema textarea Да -
schemaType select Нет -
inputFormat text Нет -
includeImpactAnalysis checkbox Нет -

Формат ответа

{
  "key": {...},
  "metadata": {
    "key": "value"
  },
  "error": "Error message (optional)",
  "message": "Notification message (optional)"
}
Данные JSON: Данные JSON

Документация MCP

Добавьте этот инструмент к конфигурации сервера MCP: 

{
  "mcpServers": {
    "elysiatools-openapi-diff-breach-detector": {
      "name": "openapi-diff-breach-detector",
      "description": "Сравнивает схемы OpenAPI или GraphQL, помечает ломающие изменения и формирует отчет о влиянии для API-команд",
      "baseUrl": "https://elysiatools.com/mcp/sse?toolId=openapi-diff-breach-detector",
      "command": "",
      "args": [],
      "env": {},
      "isActive": true,
      "type": "sse"
    }
  }
}

Вы можете объединять несколько инструментов, например: `https://elysiatools.com/mcp/sse?toolId=png-to-webp,jpg-to-webp,gif-to-webp`, максимум 20 инструментов.

Если вы столкнулись с проблемами, пожалуйста, свяжитесь с нами по адресу [email protected]