OpenAPI Diff

O que esta ferramenta verifica — e o que «incompatível» realmente significa

Uma alteração é incompatível quando um cliente escrito corretamente contra a especificação antiga pode falhar contra a nova sem mudar uma linha do seu próprio código. Essa definição guia cada veredicto desta página. Remover um caminho ou uma operação é incompatível porque as chamadas existentes não têm para onde ir. Remover um estado de resposta —sobretudo um 2xx— é incompatível porque o tratamento de erros do cliente foi escrito em torno do conjunto antigo. Adicionar um parâmetro obrigatório ou uma propriedade de pedido obrigatória é incompatível porque o pedido válido de ontem é subitamente rejeitado. Mudar o tipo ou o formato de um campo é incompatível porque analisadores, validadores e SDK gerados dependem do tipo declarado. Remover um valor de enumeração é incompatível porque um cliente pode continuar a enviá-lo, ou guardar dados que já não consegue interpretar. Tudo o resto —um endpoint novo, um parâmetro opcional, um campo de resposta novo, um valor de enumeração novo, um código de estado novo— é relatado como compatível: os clientes antigos continuam a funcionar, mesmo que ainda não possam usar a nova capacidade.

A comparação é estrutural, não textual. Ambos os documentos são normalizados no mesmo modelo antes de qualquer comparação: cada caminho e operação, os seus parâmetros indexados por nome e localização, o seu corpo de pedido e cada resposta reduzidos a uma assinatura de esquema: um resumo determinístico de tipos, formatos, nomes de propriedades, listas de obrigatórios e valores de enumeração, construído recursivamente e com as referências locais $ref resolvidas. É por isso que reordenar chaves, reformatar espaços ou reescrever cada descrição produz uma comparação vazia: nada disso muda o contrato. E é por isso que uma alteração enterrada a três níveis dentro de um esquema referenciado também é encontrada: a assinatura expande a referência em vez de comparar o seu nome.

São aceites duas formas de entrada porque o ecossistema publica ambas: primeiro tenta-se JSON e, quando isso falha, o texto é analisado como YAML, o formato que a maioria dos documentos OpenAPI escritos à mão usa. Os documentos Swagger 2.0 também funcionam, incluindo os seus parâmetros in: body e os esquemas por resposta. Deliberadamente não há obtenção remota nem envio: cole os documentos ou largue os ficheiros, tal como faria com uma captura HAR, e a comparação é executada quando prime o botão —não a cada tecla—, pelo que duas especificações grandes coladas continuam responsivas.

Use o resultado como uma porta de publicação, não como decoração. Numa revisão, a lista de incompatíveis é a agenda: cada entrada precisa de uma correção, uma subida de versão, uma janela de obsolescência ou uma decisão escrita de que a rutura é intencional e foi comunicada. A lista de compatíveis é o rascunho do registo de alterações. Exportar a comparação como JSON permite arquivar essa decisão junto à versão, e o resumo copiável entra diretamente num pedido de alteração: a mesma disciplina que aplicaria a uma alteração de contrato de webhook, onde uma carga alterada em silêncio quebra todos os subscritores de uma só vez.

Limites honestos, ditos com clareza. Esta ferramenta compara o contrato declarado: não consegue ver o comportamento que a especificação não declara, como um campo que mantém o tipo mas muda o significado, uma regra de negócio nova, limites de taxa mais apertados ou uma mensagem de erro que os clientes analisavam (imprudentemente). Segue as referências locais e compara esquemas até uma profundidade limitada, pelo que os esquemas patologicamente aninhados ou mutuamente recursivos são resumidos em vez de expandidos para sempre. E uma comparação com zero alterações incompatíveis não é uma promessa de que uma atualização seja segura: é a evidência de que o contrato documentado se manteve, que é exatamente a evidência que vale a pena ter antes de implementar.