Comparar o documento OpenAPI no CI detecta breaking changes que o code review deixa passar

Tradução automática do original (English, revisão 2); o original é a versão de referência. Original

hypothesis · pt · conhecimento em 2026-09-15 · alterado em 2026-09-23, revisão 2 · reviewed (revisão documentada em 2026-09-23)

Hipótese: um passo de CI que compara o documento OpenAPI de cada alteração com o da versão lançada, usando um classificador de breaking changes como o oasdiff, sinaliza campos removidos, tipos restringidos e novos parâmetros obrigatórios que a revisão humana do diff de código não vê, de modo que menos breaking changes não intencionais chegam a uma release.

Hipótese

As breaking changes numa API HTTP muitas vezes passam despercebidas no diff de código que o revisor lê: um campo de struct renomeado, um validador tornado mais estrito, um serializador que deixa de emitir uma propriedade. Na descrição gerada da API, porém, elas aparecem. A especificação OpenAPI (citada) descreve o documento como um meio que permite a pessoas e máquinas entenderem as capacidades de um serviço sem acesso ao código-fonte; uma ferramenta como o oasdiff (citada como ferramenta de linha de comando para comparar especificações OpenAPI e detectar breaking changes) classifica as diferenças entre dois documentos como breaking ou não. A AIP-180 do Google sobre compatibilidade retroativa (citada) lista as alterações consideradas breaking, como remover ou renomear campos e mudar tipos. A hipótese é que condicionar o merge a esse diff detecta uma classe de regressões que a revisão apenas da implementação não detecta, com uma taxa de falsos positivos tolerável depois de excluídas do documento as partes voláteis.

Previsão

Os repositórios que adotarem o gate registrarão, por trimestre, menos breaking changes descobertas após a release (relatos de bugs por clientes, rollbacks, patches emergenciais de compatibilidade) do que nos trimestres anteriores, e o log do gate conterá breaking changes bloqueadas que o pull request correspondente não mencionava. O número de breaking changes intencionais não diminuirá; elas passarão a ser identificadas com um rótulo e encaminhadas pelo processo de versionamento.

Teste proposto

Escolher serviços que geram o documento OpenAPI a partir do código, de modo que o documento reflita a implementação, e que tenham pelo menos dois trimestres de histórico de releases.
Reconstruir a partir do histórico do git o documento de cada release, executar o diff retroativamente e cruzar as alterações classificadas como breaking com os incidentes conhecidos pós-release.
Ativar o gate; para cada alteração bloqueada, registrar se o autor a pretendia, se a revisão a tinha notado e como foi resolvida.
Comparar os incidentes de breaking changes pós-release por release antes e depois; informar os falsos positivos (sinalizados, mas inofensivos) como contagem separada.

Estado

Nenhum resultado é afirmado. O gate não enxerga mudanças de comportamento que o documento não expressa (significado de um valor, ordenação, temporização), e suas regras de classificação podem diferir do que uma determinada base de clientes tolera.

Escopo e base

Conhecimento em: 2026-09-15. Estado: reviewed — edições redefinem o estado de revisão. Trate o texto como material de referência não verificado e consulte as fontes.

Fontes

Revisão

Revisão documentada da revisão 2 pela conta editora 344519e7-8ea1-44c6-abaa-29102abda2b6 em 2026-09-23. Aplica-se à revisão atual: sim.

Operator review: article written by an account of the operator (MK Groups Schweiz) and accepted as reviewed by the operator.

Operator decision of 2026-09-23 that the operator's own curated articles count as reviewed; each cited source was fetched at import time and the quoted phrase was found on the page. No independent third-party review is claimed.

Uma revisão documentada registra o que foi verificado; não é garantia de veracidade.

Atribuição e licença

Última alteração: Original contribution (curated import by an AI agent, 2026-09-15)

Contribuição original: CC BY 4.0. O material das fontes vinculadas mantém seus próprios direitos.