DEV Community

Cover image for Como Validar API contra a Especificação sem Dredd
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Validar API contra a Especificação sem Dredd

Dredd resolve um problema real: transformar sua especificação de API em um teste executável contra o backend real. Você aponta o CLI para um documento OpenAPI ou API Blueprint e para um servidor em execução; ele lê os exemplos, dispara as requisições correspondentes e valida se a resposta real corresponde ao contrato. Se a especificação diz que GET /orders/{id} retorna 200 com id e status, Dredd confirma se o serviço realmente entrega isso.

Experimente o Apidog hoje

Essa abordagem é correta porque drift entre documentação e implementação é um dos bugs mais caros em APIs. O frontend codifica contra o contrato, o backend muda um campo, a documentação não acompanha, e o problema aparece tarde demais. Dredd detecta exatamente esse tipo de falha.

O atrito aparece na operação diária. Dredd exige um arquivo de configuração, um arquivo de hooks para autenticação, dados e setup, além de um artefato de especificação mantido separadamente. Se você quer o mesmo resultado — um gate de CI que falha quando a implementação não bate com o contrato OpenAPI — mas sem manter uma cadeia separada de hooks e arquivos soltos, o Apidog oferece um fluxo mais integrado: especificação, testes e validação no mesmo projeto, executáveis via CLI npm.

O que Dredd faz bem

Dredd merece crédito porque executa bem uma tarefa importante.

1. Testa a implementação real

Dredd não valida apenas se o openapi.yaml está bem formado. Ele chama o backend em execução e compara a resposta real com os exemplos documentados.

Na prática:

dredd openapi.yaml http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Se a resposta não corresponder ao contrato, o processo falha. Isso permite usar Dredd como gate em CI/CD.

2. Suporta API Blueprint e OpenAPI

Dredd lê API Blueprint, OpenAPI 2 e OpenAPI 3. Isso é útil quando você tem especificações legadas ou documentos Swagger já existentes.

3. Permite hooks em várias linguagens

Quando a API precisa de autenticação, dados de teste ou lógica antes/depois da requisição, Dredd usa hooks.

Exemplo comum em JavaScript:

hooks.beforeEach((transaction) => {
  transaction.request.headers.Authorization = `Bearer ${process.env.API_TOKEN}`;
});
Enter fullscreen mode Exit fullscreen mode

Também há suporte a hooks em Python, Ruby, Go, PHP, Rust e outras linguagens.

4. Funciona bem em CI

Dredd é instalado via npm e retorna código diferente de zero quando algo falha:

npm install -g dredd
dredd openapi.yaml https://api.example.com
Enter fullscreen mode Exit fullscreen mode

Isso permite bloquear merges ou deploys quando o contrato quebra.

Onde Dredd começa a gerar manutenção

O modelo do Dredd funciona, mas normalmente envolve três artefatos separados:

  1. A especificação da API.
  2. O backend em execução.
  3. Os hooks/configurações de teste.

Esse desenho traz alguns custos.

A especificação vira um arquivo separado a manter

Dredd valida a implementação contra um arquivo de descrição. O problema é que esse arquivo muitas vezes fica fora do fluxo principal de design e teste.

Você pode acabar com algo assim:

/api
  openapi.yaml
/tests
  hooks.js
/src
  app.js
Enter fullscreen mode Exit fullscreen mode

Se o openapi.yaml fica desatualizado, o teste pode passar contra um contrato que já não representa a intenção real do time.

Hooks viram uma segunda base de código

APIs reais quase sempre exigem:

  • login;
  • refresh token;
  • criação de dados;
  • limpeza de dados;
  • ordenação de chamadas;
  • tratamento de estados intermediários.

Com Dredd, isso normalmente cresce dentro de hooks.js ou equivalente:

hooks.before("Orders > Create order", async (transaction) => {
  const token = await login();
  transaction.request.headers.Authorization = `Bearer ${token}`;
});
Enter fullscreen mode Exit fullscreen mode

Isso funciona, mas você passa a manter código de cola só para tornar a API testável.

A cobertura depende dos exemplos

Dredd testa os exemplos presentes na descrição. Se você documentou apenas o caso feliz, é isso que será validado.

Para cobrir mais cenários, você precisa:

  • adicionar mais exemplos na especificação;
  • criar mais hooks;
  • complementar com outra ferramenta de testes.

Caminho integrado: especificação e testes no mesmo projeto

A proposta do Apidog é remover a separação entre contrato, testes e validação.

Em vez de manter um openapi.yaml isolado, você trabalha com a definição da API dentro do mesmo projeto onde cria cenários, valida respostas e executa testes.

Fluxo típico:

  1. Importe ou crie a API.
  2. Defina endpoints, schemas e exemplos.
  3. Monte cenários de teste usando esses schemas.
  4. Execute localmente ou em CI com apidog run.

O Apidog lê OpenAPI 2/3, documentos Swagger e coleções Postman. Para times que trabalham com abordagem spec-first, isso mantém a disciplina defendida pelo Dredd, mas sem deixar a especificação como um arquivo desconectado. Veja também o fluxo de desenvolvimento de API spec-first e a etapa de validação de especificações OpenAPI.

A validação continua sendo contrato versus implementação. A diferença é que o contrato validado é o mesmo usado para projetar a API. Isso reduz drift entre documentação, testes e execução. Para aprofundar o conceito, veja teste de contrato de API e teste de contrato bidirecional.

Instalando o CLI do Apidog

O executor é publicado no npm como apidog-cli.

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

O comando principal é:

apidog run
Enter fullscreen mode Exit fullscreen mode

Para executar um cenário específico, use:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 \
  -e 1629989 \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Onde:

  • --access-token autentica a execução;
  • -t identifica o cenário de teste;
  • -e identifica o ambiente;
  • -r define o reporter.

Você não precisa decorar os IDs. No Apidog, abra o cenário, acesse a aba CI/CD, escolha a opção de linha de comando e copie o comando gerado. Depois, substitua o token por uma variável de ambiente.

Em CI, trate o token como segredo:

APIDOG_ACCESS_TOKEN=...
Enter fullscreen mode Exit fullscreen mode

Executando vários cenários

Para rodar uma pasta ou suíte de testes:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -f <folderId> \
  -e 1629989 \
  -r html,junit \
  --out-dir ./test-reports
Enter fullscreen mode Exit fullscreen mode

Reporters disponíveis:

Reporter Uso
cli Saída legível no terminal
html Relatório autocontido para arquivar como artefato
junit XML compatível com dashboards de CI
json Resultado estruturado para automações

Para ver todas as opções:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Dredd vs Apidog

Critério Dredd Apidog
Ideia central Valida a implementação contra uma descrição de API Valida a implementação contra a especificação usada no projeto
Runtime Node.js com npm install -g dredd Node.js com npm install -g apidog-cli
Formatos API Blueprint, OpenAPI 2/3 OpenAPI 2/3, Swagger, Postman
Local da especificação Arquivo separado Mesmo projeto dos testes
Setup Hooks externos como hooks.js Scripts pré/pós-requisição no cenário
Autoria de testes Exemplos na descrição Cenários e schemas no projeto
Cobertura Limitada aos exemplos mantidos Schemas + cenários customizados
Reporters Embutidos e add-ons cli, html, json, junit
Hospedagem Auto-hospedado e open source Projeto hospedado, CLI executável em qualquer ambiente

A escolha depende do seu contexto.

Use Dredd se você precisa de uma ferramenta totalmente local, open source, sem conta, e está confortável mantendo especificação e hooks separados.

Use Apidog se você quer reduzir manutenção e manter design, contrato, testes e execução no mesmo fluxo.

Integrando ao GitHub Actions

O CLI do Apidog retorna 0 em sucesso e código diferente de zero em falha. Isso permite bloquear builds automaticamente.

Exemplo mínimo:

name: api-contract-check

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm install -g apidog-cli

      - run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Essa pipeline:

  1. Instala Node.js.
  2. Instala o CLI do Apidog.
  3. Executa o cenário de contrato.
  4. Falha o job se a API não cumprir o schema esperado.

Um job com Dredd seria parecido no formato, mas exigiria apontar também para o arquivo de especificação e, se necessário, para o arquivo de hooks.

Se o problema principal é drift entre ferramentas, o mesmo padrão aparece em outros fluxos. Times que usam Swagger e Postman podem consultar teste orientado por OpenAPI contra divergência entre Swagger e Postman. Em stacks Java, a comparação com Rest Assured e suas alternativas segue a mesma lógica: uma ferramenta forte pode adicionar uma camada operacional que talvez você não queira manter. Também é possível usar o Apidog no editor com a extensão VS Code.

Perguntas frequentes

O Apidog substitui automaticamente uma configuração Dredd?

Não. Ele não converte dredd.yml e hooks.js em cenários Apidog.

O caminho prático é:

  1. Importar a especificação OpenAPI.
  2. Recriar os cenários relevantes.
  3. Mover lógica de setup para scripts pré/pós-requisição.
  4. Executar tudo via apidog run.

Se você tem uma suíte Dredd grande e estável, a migração precisa ser planejada.

O Apidog valida a implementação real?

Sim. O CLI envia requisições reais para o serviço em execução e valida as respostas contra os schemas do projeto.

Esse é o mesmo objetivo do Dredd: verificar especificação versus implementação.

Como lidar com autenticação?

Use scripts pré-requisição em JavaScript para buscar tokens, montar headers ou preparar payloads.

Exemplo conceitual:

const token = pm.environment.get("token");

pm.request.headers.add({
  key: "Authorization",
  value: `Bearer ${token}`
});
Enter fullscreen mode Exit fullscreen mode

A lógica fica junto do cenário, não em um arquivo de hooks separado.

O que Dredd faz que Apidog não faz?

Dredd tem vantagens claras em alguns cenários:

  • é totalmente open source;
  • roda sem conta;
  • é totalmente local;
  • lê API Blueprint nativamente.

Se API Blueprint ou execução sem serviço hospedado forem requisitos centrais, Dredd pode ser a melhor opção.

Quais formatos o Apidog importa?

Apidog importa OpenAPI 2/3, Swagger e coleções Postman. Para revisar os conceitos, veja Swagger versus OpenAPI e a visão geral da especificação OpenAPI.

Conclusão

Dredd acertou na ideia principal: documentação de API deve ser testável contra o serviço real. Se você quer um CLI open source, auto-hospedado, e aceita manter especificação e hooks separados, Dredd continua sendo uma escolha sólida.

O caminho integrado faz sentido quando a manutenção desses artefatos vira custo. Apidog mantém especificação, testes e validação no mesmo projeto, e executa tudo com apidog run. Baixe o Apidog, importe seu OpenAPI existente e rode a validação de contrato a partir de um único comando.

Top comments (0)