01
Defina anterior e atual
A classificação considera clientes do contrato antigo. Trocar as entradas mostra uma prévia e permite desfazer uma vez, restaurando entradas e resultado.
Contratos de API
comparador OpenAPIConfira o impacto antes da entrega
Cole a especificação anterior e a nova, depois execute a comparação.
comparador OpenAPI
Especificação anterior
Nova especificação
Relatório de mudanças
As duas especificações são processadas neste navegador; nenhuma solicitação de API é enviada.
Opções de comparação
Escopo: operações, parâmetros, corpos de requisição e respostas acompanhados. Não prova compatibilidade real.
Cole as duas especificações para comparar.
O comparador OpenAPI ajuda quando uma nova versão muda o contrato que clientes já utilizam. Um diff textual não revela facilmente se remover uma rota ou exigir um parâmetro torna uma chamada antiga inválida.
Use o diff OpenAPI para comparar especificações OpenAPI por operação. Mudanças incompatíveis ficam separadas das que exigem revisão; o resultado não promete compatibilidade do serviço em produção.
Por que usar o comparador OpenAPI
Enxergue o risco na direção correta
O comparador OpenAPI avalia a passagem do contrato anterior para o novo. Remover um campo da resposta e adicionar uma rota aparecem como achados diferentes.
Mantenha as exclusões auditáveis
O caminho exato é ignorado nos dois documentos e aparece na lista de exclusões do relatório. Assim a equipe sabe o que ficou fora da análise.
Três escolhas antes de gerar o relatório
02
Ignore somente o caminho completo
Digite /internal/health, por exemplo, com um path OpenAPI por linha. Não há coringa ou expressão regular; editar a lista invalida o relatório anterior.
03
Use o filtro sem cortar a exportação
A seleção de risco só reduz os itens visíveis. Os arquivos JSON e Markdown continuam incluindo todos os achados e caminhos ignorados.
O que a análise registra
Operações e métodos
Uma rota ou método removido é candidato a quebra de compatibilidade. Uma operação nova é registrada à parte, sem misturá-la aos riscos.
Entradas e respostas
Parâmetros e propriedades obrigatórios novos, status removidos e campos de resposta excluídos são destacados. Tipos e enum simples são avaliados quando referências locais podem ser resolvidas.
Evidência para revisão
Cada mudança informa método, caminho, regra e valores antes/depois. O relatório completo pode ser copiado ou baixado apenas após uma comparação válida.
Limites do parecer estático
- Sem buscar URLs
- A ferramenta processa o JSON ou YAML colado, sem buscar documentos remotos, chamar a API real ou enviar as especificações.
- Exclusão por caminho exato
- Coringas, regex e rotas callback não são interpretados. Renomear um path aparece como remoção e adição.
- Referências incompletas interrompem
- Um $ref externo, dialeto não coberto, webhook ou callback impede um novo relatório de risco completo.
- Sem prova em tempo de execução
- Quebras de compatibilidade dependem também do servidor e dos clientes. Teste consumidores afetados antes de publicar.
Dúvidas sobre o comparador OpenAPI
Quais formatos de schema a ferramenta suporta?
Swagger 2.0 e OpenAPI 3.0/3.1 em JSON ou YAML são aceitos. Cole um documento antigo e um novo; pacotes com referências externas não entram na análise completa.
O que é considerado uma 'breaking change'?
É uma alteração que pode invalidar chamadas antes válidas, como remover uma rota ou tornar uma entrada obrigatória. O comparador OpenAPI sinaliza o risco do contrato, não garante o resultado em produção.
Posso desativar a análise de impacto?
Não. A análise de impacto sempre acompanha o relatório, porque sem ela uma mudança removida poderia parecer uma simples diferença textual. Você pode filtrar a categoria visível.
A ferramenta detecta mudanças que não quebram a API?
Sim. Adições de rotas e entradas opcionais são registradas separadamente. Novos status ou campos de resposta ficam para revisão, pois clientes estritos podem reagir a eles.
Como o risco da release é calculado?
O risco não é uma pontuação arbitrária da release: cada achado segue uma regra e uma categoria. Examine as mudanças marcadas e teste os clientes antes de concluir.
Esta comparação ajudou?
Abra o comparador OpenAPI antes da release
O comparador OpenAPI entrega mudanças rastreáveis e evidencia seus limites. Confirme riscos com testes de consumidores.