Detector de breaking changes de API e planejador de migracao

Compara dois schemas OpenAPI 3.x, encontra mudancas incompatíveis e sugere estrategias de migracao

Ajuda equipes de API a avaliar remocoes de campos, restricoes de tipo e novas obrigatoriedades.

Exemplos de resultados

1 Exemplos

Detectar breaking changes entre versoes da API

Compara dois esquemas OpenAPI e identifica mudancas que podem quebrar clientes atuais

Breaking changes are grouped by impact with migration strategies.
Ver parâmetros de entrada
{ "oldSchema": "openapi: 3.0.3\npaths:\n /users:\n post:\n requestBody:\n required: false\n content:\n application/json:\n schema:\n type: object\n properties:\n name: { type: string }\n responses:\n \"200\":\n description: ok\n content:\n application/json:\n schema:\n type: object\n properties:\n id: { type: string }\n name: { type: string }\n", "newSchema": "openapi: 3.0.3\npaths:\n /users:\n post:\n requestBody:\n required: true\n content:\n application/json:\n schema:\n type: object\n required: [name, role]\n properties:\n name: { type: string }\n role: { type: string }\n responses:\n \"200\":\n description: ok\n content:\n application/json:\n schema:\n type: object\n properties:\n id: { type: string }\n" }

Fatos principais

Categoria
Desenvolvimento e Web
Tipos de entrada
textarea
Tipo de saída
html
Cobertura de amostras
4
API disponível
Yes

Visão geral

O Detector de Breaking Changes de API é uma ferramenta essencial para desenvolvedores e arquitetos de software que precisam comparar duas versões de um schema OpenAPI 3.x. Ele analisa o schema antigo e o novo para identificar alterações incompatíveis, como remoção de campos, mudanças de tipos de dados ou novas propriedades obrigatórias, gerando um relatório detalhado com estratégias de migração para evitar quebras de integração nos clientes atuais.

Quando usar

  • •Antes de lançar uma nova versão da API em produção para garantir que clientes existentes não sejam afetados.
  • •Durante a revisão de pull requests (PRs) que alteram os contratos da API para validar o impacto das mudanças.
  • •Ao planejar a depreciação de endpoints ou campos antigos, buscando estratégias de migração seguras.

Como funciona

  • •Cole o schema OpenAPI 3.x da versão atual (antiga) no campo 'Schema OpenAPI antigo'.
  • •Insira o schema OpenAPI 3.x da nova versão proposta no campo 'Schema OpenAPI novo'.
  • •A ferramenta processa e compara ambos os contratos, detectando alterações estruturais e de validação.
  • •Um relatório em HTML é gerado, destacando as quebras de compatibilidade (breaking changes) e sugerindo ações de mitigação.

Casos de uso

Prevenção de falhas em aplicativos mobile ou web que consomem a API após uma atualização de backend.
Auditoria de contratos de API em arquiteturas de microsserviços para manter a compatibilidade entre equipes.
Geração de documentação de changelog focada em alterações críticas para os consumidores da API.

Exemplos

1. Identificando novos campos obrigatórios

Desenvolvedor Backend
Contexto
A equipe adicionou um novo sistema de permissões e atualizou o contrato da API de criação de usuários.
Problema
Garantir que a adição do campo 'role' não quebre os clientes que já utilizam o endpoint de criação.
Como usar
Cole o schema antigo sem o campo 'role' e o novo schema onde 'role' é obrigatório nos respectivos campos de texto.
Resultado
A ferramenta alerta que tornar o campo 'role' obrigatório no requestBody é um breaking change e sugere torná-lo opcional com um valor padrão na versão atual.

2. Detectando remoção de campos na resposta

Arquiteto de Soluções
Contexto
Um endpoint de listagem de usuários foi refatorado para melhorar a performance, removendo dados redundantes.
Problema
Verificar se algum campo utilizado pelos clientes atuais foi removido inadvertidamente da resposta (response).
Como usar
Insira o schema original no campo 'Schema OpenAPI antigo' e o schema refatorado no campo 'Schema OpenAPI novo' para iniciar a comparação.
Resultado
O relatório HTML destaca a remoção do campo 'name' da resposta 200, classificando-o como alto impacto e sugerindo a manutenção do campo como 'deprecated' antes da remoção definitiva.

Testar com amostras

development
Coleções Postman - Testes de API
Exemplos abrangentes de coleções Postman incluindo testes de API, scripts de automação, variáveis de ambiente, servidores mock e padrões avançados de teste para REST APIs
title token api
sample
Exemplos OpenAI API
Exemplos abrangentes da API OpenAI incluindo modelos GPT, geração de imagens DALL-E, processamento de áudio Whisper e chamadas de função
title token api
sample
API Gráfica WebGPU
API gráfica moderna para gráficos 3D de alta performance e computação GPU no navegador
title token api
sample
Exemplos do Truffle Development Suite
Exemplos do framework de desenvolvimento Ethereum Truffle incluindo contratos inteligentes, testes, implantação, migrações, depuração e fluxos de trabalho de desenvolvimento
keywords migration,contract,testing
sample

FAQ

Quais versões do OpenAPI são suportadas?

A ferramenta suporta a comparação de schemas no formato OpenAPI 3.x.

O que é considerado um breaking change?

Alterações que quebram a integração do cliente, como remover um endpoint, excluir um campo de resposta, alterar o tipo de um dado ou tornar um campo de requisição obrigatório.

A ferramenta corrige os schemas automaticamente?

Não, ela atua como um analisador estático. O resultado aponta os problemas e sugere estratégias de migração, mas a correção deve ser feita manualmente no seu código.

Posso comparar contratos em JSON e YAML?

Sim, você pode colar o conteúdo do seu schema em formato YAML ou JSON diretamente nos campos de texto.

Os meus schemas de API são armazenados no servidor?

O processamento ocorre com os dados fornecidos na interface, sem armazenamento persistente dos seus contratos de API.

Documentação da API

Ponto final da solicitação

POST /pt/api/tools/api-breaking-changes-detector-migration-planner

Parâmetros da solicitação

Nome do parâmetro Tipo Requerido Descrição
oldSchema textarea Não -
newSchema textarea Não -

Formato de resposta

{
  "result": "
Processed HTML content
",
  "error": "Error message (optional)",
  "message": "Notification message (optional)",
  "metadata": {
    "key": "value"
  }
}
HTML: HTML

Documentação de MCP

Adicione este ferramenta à sua configuração de servidor MCP: 

{
  "mcpServers": {
    "elysiatools-api-breaking-changes-detector-migration-planner": {
      "name": "api-breaking-changes-detector-migration-planner",
      "description": "Compara dois schemas OpenAPI 3.x, encontra mudancas incompatíveis e sugere estrategias de migracao",
      "baseUrl": "https://elysiatools.com/mcp/sse?toolId=api-breaking-changes-detector-migration-planner",
      "command": "",
      "args": [],
      "env": {},
      "isActive": true,
      "type": "sse"
    }
  }
}

Você pode encadear várias ferramentas, ex: `https://elysiatools.com/mcp/sse?toolId=png-to-webp,jpg-to-webp,gif-to-webp`, máx 20 ferramentas.

Se você encontrar algum problema, por favor, entre em contato conosco em [email protected]