Contratos e compatibilidade

Um contrato regista a estrutura que uma operação de API promete. O Echo reúne o método, o caminho, o documento e as versões publicadas. Um mock pode gerar dados a partir de um contrato e uma aplicação pode associar-se a uma versão para declarar uma dependência. Publicar um contrato não implementa nem testa uma API em execução.

Crie e publique

Abra Contratos no Maestro, crie o contrato e abra Publicar versão. Cole um documento de contrato Echo e reveja-o antes de publicar. Este campo espera JSON de um documento Echo, não uma resposta de exemplo nem um JSON Schema por converter. A conversão de esquemas está disponível no editor de rotas de mocks.

As versões publicadas são retratos numerados. A associação de uma aplicação regista a versão acordada. O diff na web mostra caminhos alterados, motivos e veredictos separados para consumidores e fornecedores. Reutilizar conteúdo já publicado pode devolver uma versão anterior existente em vez de criar outra.

Leia a direção certa

A associação Consumes indica que a aplicação chama a operação. Provides indica que a fornece. A comparação distingue alterações de pedido e de resposta e avalia cada lado.

Estes são os veredictos do classificador atual. Um campo opcional extra na resposta é condicional porque JsonUnmappedMemberHandling.Disallow rejeita campos desconhecidos. Leia a condição e o motivo no diff. Safe significa que não foi encontrada incompatibilidade para esse lado; Warning pede revisão; Breaking identifica incompatibilidade; ConditionalBreaking depende da condição indicada. Um veredicto desconhecido não é aprovação.

Reveja antes de aceitar

Criar, publicar e comparar contratos no Maestro está incluído em todos os planos do Echo, incluindo o Free. Publicar a partir do seu próprio código precisa de uma chave de aplicação, e emitir chaves faz parte do Echo Pro e Pro AI e requer Echo/ManageHosting, permissão atribuída por omissão ao administrador da organização num plano pago. Um fornecedor pode publicar através de EchoContractPublicationClient, do Gapfy.Echo.Contracts. Crie primeiro o contrato e a associação Provides, depois use uma chave com PublishOwnedContracts. O cliente publica uma versão de um contrato próprio; não cria contratos nem assume propriedade.

A publicação termina antes de devolver os resultados de compatibilidade. Um veredicto incompatível não anula a publicação. Reveja as diferenças antes de alterar um consumidor ou aceitar uma nova referência.

O Gapfy.Echo.Testing compara contratos consumidos com retratos revistos no seu repositório. Pode fazer falhar o CI quando uma mudança quebra esse consumidor. Não testa a API em execução nem valida os contratos que a aplicação fornece.

Construa um contrato de resposta no desktop

Abra uma rota de mock e escolha o modo de resposta Contrato. Comece por um exemplo JSON, examine a estrutura inferida e reveja as ambiguidades antes de guardar. Selecione um campo para escolher um gerador compatível e confira as pré-visualizações com um caminho de pedido representativo. Um exemplo guardado é um ponto de partida; não descreve automaticamente todas as respostas possíveis.

Adicione cenários com nome para situações como resultado vazio ou operação recusada. Dê um exemplo a cada cenário e selecione-o para examinar a resposta gerada. Envie X-Echo-Scenario: empty para pedir um cenário chamado empty; omita o cabeçalho para usar a resposta predefinida. X-Echo-Seed permite repetir a geração aleatória. Uma seed fixa não congela geradores que usam a data atual. Uma rota fixada numa versão publicada não pode editar essa versão diretamente.

Importe modelos sem os reescrever

Com uma conta autenticada e ligação à rede, abra Importar e exportar modelos no editor de contratos do desktop.

1. Escolha C#, TypeScript, JavaScript, Java, Python ou JSON Schema.
2. Cole o código ou abra os ficheiros relacionados em conjunto. Inclua os tipos referenciados e indique o tipo raiz quando houver vários.
3. Em C#, escolha se os nomes das propriedades devem usar camelCase. Os nomes JSON explícitos têm prioridade.
4. Confira a pré-visualização da conversão. Leia o documento, o schema e os diagnósticos antes de aplicar.
5. Aplique a pré-visualização concluída à rota. Fechar o diálogo ou uma conversão falhada mantém a rota intacta. Alterar a entrada exige uma nova pré-visualização.

Use o exemplo da linguagem selecionada para conferir a estrutura esperada antes de importar o seu modelo.

A conversão lê o código sem o executar. Dependências em falta e construções incompatíveis produzem diagnósticos. Valores JavaScript em execução não bastam para deduzir um modelo completo. Serializadores próprios, polimorfismo e estruturas recursivas podem exigir um schema explícito compatível. Os schemas importados continuam associados ao contrato quando edita o exemplo ou o caminho da rota; atualize a estrutura pela importação, em vez de substituir geradores individuais.

Exporte modelos para outra aplicação

Escolha a linguagem de saída e exporte o contrato atual. Examine os ficheiros gerados, copie um ou guarde o ZIP completo, que inclui contract.schema.json. Os mesmos seis formatos estão disponíveis para exportação. Exportar lê o documento atual e não publica outra versão.

Reveja os diagnósticos sobre precisão numérica e diferenças entre campos ausentes e nulos. Os tipos gerados não impõem, por si só, todas as regras de intervalos, enums ou propriedades adicionais; mantenha a validação de schema onde a sua aplicação precisar dessas garantias. A exportação Python inclui from_dict e to_dict; os valores Decimal precisam de um codificador JSON apropriado.

Próximos passos

Ligue a sua aplicação com aplicações e chaves ou use o documento para servir mocks na hospedagem pública.