Contratos e compatibilidade

Um contrato registra 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 se vincular 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 revise antes de publicar. Esse campo espera JSON de um documento Echo, não uma resposta de exemplo nem um JSON Schema sem conversão. A conversão de esquemas está disponível no editor de rotas de mocks.

As versões publicadas são retratos numerados. O vínculo de uma aplicação registra a versão acordada. O diff na web mostra caminhos alterados, motivos e avaliações separadas 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

O vínculo Consumes indica que a aplicação chama a operação. Provides indica que ela fornece a operação. A comparação distingue alterações de requisição e de resposta e avalia cada lado.

Essas são as avaliações 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 aquele lado; Warning pede revisão; Breaking identifica incompatibilidade; ConditionalBreaking depende da condição indicada. Uma avaliação desconhecida não é aprovação.

Revise 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 exige Echo/ManageHosting, permissão concedida por padrão ao administrador da organização em um plano pago. Um fornecedor pode publicar por EchoContractPublicationClient, do Gapfy.Echo.Contracts. Primeiro crie o contrato e o vínculo 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. Uma avaliação incompatível não desfaz a publicação. Revise as diferenças antes de alterar um consumidor ou aceitar uma nova referência.

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

Monte 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 revise as ambiguidades antes de salvar. Selecione um campo para escolher um gerador compatível e confira as prévias com um caminho de requisição representativo. Um exemplo salvo é um ponto de partida; ele não descreve automaticamente todas as respostas possíveis.

Adicione cenários nomeados 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 header para usar a resposta padrão. 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 em uma versão publicada não pode editar essa versão diretamente.

Importe modelos sem reescrevê-los

Com uma conta conectada e acesso à 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 arquivos relacionados juntos. Inclua os tipos referenciados e informe o tipo raiz quando houver vários.
3. Em C#, escolha se os nomes das propriedades devem usar camelCase. Nomes JSON explícitos têm prioridade.
4. Confira a prévia da conversão. Leia o documento, o schema e os diagnósticos antes de aplicar.
5. Aplique a prévia concluída à rota. Fechar o diálogo ou uma conversão com falha mantém a rota intacta. Alterar a entrada exige uma nova prévia.

Use o exemplo do idioma de programação selecionado para conferir a estrutura esperada antes de importar seu modelo.

A conversão lê o código sem executá-lo. Dependências ausentes e construções incompatíveis geram 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. Schemas importados continuam associados ao contrato quando você edita o exemplo ou o caminho da rota; atualize sua 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 arquivos gerados, copie um ou salve 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.

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

Próximos passos

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