Objetivo e escopo
Compare versoes de API, planeje migracoes e aceite a compatibilidade antes do release. As ferramentas nao substituem o deploy real nem o monitoramento.
Este guia transforma o escopo informado em um resultado revisável. Mantenha a fonte, os resultados intermediários e as decisões para que a próxima pessoa entenda o que foi verificado e por quê.
Preparar evidências e tomar decisões
Prepare as especificacoes versionadas antiga e nova e casos representativos.
Defina regras de compatibilidade, consumidores afetados, limites e um ambiente de teste autorizado.
Decisão: Qual ferramenta de comparacao escolher?. Escolha api-breaking-changes-detector-migration-planner para dois schemas OpenAPI 3.x e estrategias de migracao. Escolha openapi-diff-breach-detector para um diff orientado a impacto de schemas OpenAPI ou GraphQL.
Concluir o fluxo de trabalho
1. Compare as versoes
Valide e compare as especificacoes e classifique elementos do contrato removidos ou restringidos. Usar openapi-validator, api-breaking-changes-detector-migration-planner, openapi-diff-breach-detector.
2. Verifique a compatibilidade
Valide respostas capturadas, compare payloads e gere casos de limite ou mutacao; use requisicoes apenas em um backend autorizado. Usar api-response-contract-validator, api-response-diff-semantic-analyzer, api-contract-stress-tester, api-contract-mutation-tester.
3. Aceite o plano de migracao
Registre acoes dos consumidores, evidencias de SemVer e changelog, bloqueios ou isencoes e responsaveis separados do release e monitoramento. Usar semver-validator, changelog-extractor, package-json-dependency-auditor.
Verificar o resultado antes da entrega
- Cada descoberta de quebra tem localizacao, impacto no cliente, acao de migracao ou compatibilidade e responsavel.
- Verificacoes de resposta, limite e mutacao passam ou possuem bloqueio ou isencao explicitos; release e monitoramento tem responsaveis separados.
Perguntas frequentes
- Essas ferramentas fazem deploy ou monitoram a producao? Não. Elas analisam especificacoes, payloads salvos, casos gerados e requisicoes autorizadas de teste. O release real e o monitoramento sao separados.
- O que e uma breaking change? Remover uma operacao, campo ou status, restringir uma entrada, mudar um tipo ou tornar obrigatorio um dado opcional pode quebrar consumidores.
- O que o plano de migracao deve conter? Cada descoberta precisa de consumidor afetado, acao, responsavel, prazo, evidencia de teste e premissa de rollback.