O problema

Durante a automação de uma API de compras, alguns comportamentos encontrados na implementação não correspondiam exatamente ao que estava descrito na documentação.

A documentação indicava endpoints, métodos e exemplos de respostas, porém os testes revelaram diferenças no contrato real.

Documentação é uma referência, não uma garantia

Swagger e OpenAPI são ferramentas essenciais para entender uma API, mas a implementação final é a fonte de verdade durante a execução.

Um exemplo encontrado foi uma resposta documentada contendo campos que não estavam presentes no retorno real do endpoint. 

{
  "id": "invoice-id",
  "invoice_number": "INV-2026000007",
  "total": 14.15
}

O endpoint de consulta retornava uma estrutura mais completa: 

{
  "status": "AWAITING_FULFILLMENT",
  "invoicelines": [],
  "payment": {}
}

Como validar um contrato real de API

1. Execute o endpoint

O primeiro passo é sempre observar a resposta real da aplicação.

2. Compare request e response

Verifique:

  • nome dos campos;
  • tipos dos valores;
  • campos obrigatórios;
  • diferença entre exemplos e respostas reais.

3. Modele os tipos conforme o comportamento

Em automação com TypeScript, respostas diferentes devem possuir contratos diferentes. 

InvoiceCreateResponse

InvoiceDetailsResponse

Impacto na automação

Criar uma única interface gigante para todos os endpoints aumenta a fragilidade dos testes.

O ideal é representar cada operação da API com o contrato correspondente.

Boas práticas

  • Use Swagger para descoberta inicial.
  • Valide sempre contra respostas reais.
  • Evite confiar apenas nos exemplos da documentação.
  • Separe modelos de criação, consulta e atualização.

Conclusão

Uma automação confiável depende de entender o comportamento real da API. A documentação ajuda a começar, mas os testes precisam validar o contrato que realmente existe em execução.