Comparar OpenAPI
OpenAPI Diff
Compara dois documentos OpenAPI e separa as mudanças que quebram compatibilidade das que só acrescentam.
Compara duas versões de um documento OpenAPI e separa as mudanças em incompatíveis e aditivas. A regra que ele usa está escrita na página: uma mudança é incompatível se uma requisição que o documento antigo aceitava agora pode ser rejeitada, ou se uma resposta que ele prometia é uma que um cliente existente não consegue mais tratar.
Documento anterior
Solte a versão anterior
Lido só nesta aba.
Documento novo
Solte a versão nova
Lido só nesta aba.
Quebram
8
Aditivas
7
Veredito
Precisa de uma versão maior
GET /pets
- quebraAgora o parâmetro `in: query` `limit` é obrigatório.
- acrescentadoFoi acrescentado um parâmetro `in: query` `sort` opcional.
- mudadoO resumo ou a descrição mudou.
GET /pets · responses["200"].content["application/json"]
- quebra`[].id` mudou de tipo: de integer para string.
- quebraA propriedade `[].name` agora é opcional.
- quebra`[].status` ganhou o valor de enum "pending".
- acrescentadoFoi acrescentada uma propriedade opcional `[].owner`.
GET /pets/{petId} · responses["200"].content["application/json"]
- quebra`id` mudou de tipo: de integer para string.
- quebraA propriedade `name` agora é opcional.
- quebra`status` ganhou o valor de enum "pending".
- acrescentadoFoi acrescentada uma propriedade opcional `owner`.
GET /pets/{petId}
- quebraA resposta `404` sumiu.
DELETE /pets/{petId}
- acrescentadoA operação foi acrescentada.
components.schemas.Owner
- acrescentadoO esquema foi acrescentado.
info.version
- mudado`1.0.0` → `2.0.0`
O que conta como quebra
Em uma frase: uma requisição que o documento anterior aceitava pode passar a ser recusada, ou uma resposta que ele prometia é uma que um cliente existente já não consegue tratar. Então: tirar um caminho, uma operação, um código de resposta, um tipo de mídia ou uma propriedade de resposta; acrescentar um parâmetro obrigatório ou uma propriedade de requisição obrigatória; algo opcional virar obrigatório; uma mudança de tipo; tirar um valor de um enum de requisição; acrescentar um valor a um enum de resposta (o switch do cliente não tem um case para ele); e uma propriedade de resposta passar de obrigatória a opcional. As direções contrárias, e as mudanças em descrições, etiquetas, operationId e marcas de deprecated, são compatíveis.
- · Os esquemas são comparados depois de seguir os
$refinternos do documento, então renomear um componente não é uma mudança. Os parâmetros de caminho são pareados por posição, não por nome. - · O que há dentro de
oneOf·anyOf·noté comparado como um todo e reportado como quebra se diferir — aqui não se raciocina sobre isso. - · Um
$refque aponta para outro arquivo não é seguido. Junte os arquivos num só antes.
Para conferir um documento só, use Verificação de OpenAPI.
Como usar
Coloque o documento antigo e o novo lado a lado
JSON ou YAML para qualquer um dos dois. Os dois são analisados nesta aba, então uma especificação não publicada não sai da sua máquina.
Leia o veredicto
Contagem de incompatíveis, contagem de aditivas e o que isso significa para o número de versão: um incremento major, um minor ou nada, porque o contrato não mudou.
Filtre as incompatíveis e leia
Agrupadas por operação, cada uma com o que mudou. A cópia em Markdown tem o formato de uma descrição de pull request.
Perguntas frequentes
Por que adicionar um valor a um enum de resposta é incompatível?
Porque um cliente existente tem um switch sem case para ele. Adicionar a um enum de *requisição* é seguro: o servidor aceita mais do que antes; adicionar a um enum de resposta manda aos clientes algo de que nunca ouviram falar. A direção é o que decide.
Renomeei um componente e ele não relata mudança nenhuma.
Correto. Os esquemas são comparados depois de seguir os `$ref`, então um componente renomeado com a mesma forma é o mesmo contrato. Os nomes em `components` são internos; os clientes veem a forma resolvida.
Uma propriedade obrigatória de resposta que vira opcional é mesmo incompatível?
Sim, do lado do cliente. Prometeram a ele que o campo estaria sempre lá e o código dele lê sem condição; torná-lo opcional significa que o servidor agora pode omiti-lo. Obrigatório e opcional trocam de direção entre requisição e resposta, que é a parte que as pessoas entendem ao contrário.
Como ele trata `oneOf` e `anyOf`?
Eles são comparados como um todo e relatados como incompatíveis se diferirem em qualquer coisa. Raciocinar sobre se uma união é superconjunto de outra é um procedimento de decisão que isto deliberadamente não tenta; um “incompatível” falso que você pode descartar é melhor do que um “seguro” falso que você não pode.
Pode receber de
Comparar JSON
JSON Diff
Compara dois documentos JSON estruturalmente, ignorando a ordem das chaves e informando os caminhos adicionados, removidos e alterados.
Linter de OpenAPI
OpenAPI Linter
Verifica um documento OpenAPI em busca de respostas faltando, schemas sem uso, referências que não apontam para nada e os outros defeitos que quebram geradores de código.
Testador de faixas semver
Semver Range Tester
Verifica quais versões satisfazem uma faixa, compara duas versões e ordena uma lista por precedência.
Formatador e validador de JSON
JSON Formatter & Validator
Formata, minifica e valida JSON, apontando a linha e a coluna exatas de um erro de sintaxe.
Em seguida
Estas aceitam o que esta ferramenta produz, então o resultado pode ir direto.
Comparar JSON
JSON Diff
Compara dois documentos JSON estruturalmente, ignorando a ordem das chaves e informando os caminhos adicionados, removidos e alterados.
Validador de JSON Schema
JSON Schema Validator
Valida um documento contra um JSON Schema e informa cada falha com o caminho da instância.
Linter de OpenAPI
OpenAPI Linter
Verifica um documento OpenAPI em busca de respostas faltando, schemas sem uso, referências que não apontam para nada e os outros defeitos que quebram geradores de código.
Testador de faixas semver
Semver Range Tester
Verifica quais versões satisfazem uma faixa, compara duas versões e ordena uma lista por precedência.
JSON ⇄ CSV conversor
JSON ⇄ CSV
Achata JSON aninhado em colunas ou reconstrói objetos a partir de uma tabela, com uma regra de nome de coluna por caminho com pontos.
Formatador e validador de JSON
JSON Formatter & Validator
Formata, minifica e valida JSON, apontando a linha e a coluna exatas de um erro de sintaxe.