Como Validar API contra a Especificação sem Dredd

Dredd resolve um problema real e o resolve de forma limpa. Você o aponta para uma descrição de API, um documento OpenAPI ou um arquivo API Blueprint e para um servidor em execução. Ele lê cada exemplo na descrição, dispara a solicitação correspondente no backend ativo e verifica se a resposta real corresponde ao que a especificação prometeu. Se sua especificação diz que GET /orders/{id} retorna um 200 com um campo id e um status, Dredd confirma que o serviço em execução realmente faz isso. A especificação deixa de ser uma documentação que apodrece silenciosamente e se torna um teste que falha ruidosamente.

Essa ideia, de validar a implementação contra a descrição da API, é a ideia correta. A divergência entre o que uma especificação diz e o que um serviço faz é um dos bugs silenciosos mais caros no trabalho com APIs. Uma equipe de frontend codifica contra o contrato documentado, o backend envia uma renomeação de campo, ninguém atualiza a documentação, e a falha aparece em produção. Dredd detecta exatamente essa classe de falha e, por anos, tem sido a ferramenta de código aberto ideal para fazer isso a partir da linha de comando.

O atrito está na configuração e na manutenção, não no conceito. Dredd é um CLI Node.js que precisa de seu próprio arquivo de configuração, um arquivo de hooks em sua linguagem de escolha para qualquer coisa além de casos triviais, e um artefato de especificação separado que você mantém manualmente junto com todo o resto. Se você deseja o mesmo resultado que Dredd oferece, um portão de CI que falha quando sua implementação não corresponde mais ao seu contrato OpenAPI, sem configurar uma cadeia de ferramentas de hooks e sem manter a especificação como um terceiro arquivo desconectado, o Apidog é feito para esse fluxo de trabalho. Ele mantém a especificação, os testes e a validação em um único projeto, e executa tudo de forma headless a partir de um CLI npm. Este guia é justo sobre o que Dredd faz bem e claro sobre onde o caminho integrado vence.

O que Dredd faz bem

Primeiro, dê a Dredd o seu devido valor, porque ele conquistou a reputação.

Ele testa a implementação, não um mock. Este é o cerne da questão. Muitas ferramentas validam que seu arquivo OpenAPI está bem formado, ou que um servidor mock se comporta. Dredd faz algo mais difícil: ele atinge o backend real em execução e verifica os bytes reais que retornam em relação aos exemplos documentados. Uma execução Dredd bem-sucedida significa que seu serviço implantado e sua especificação concordam agora, não em teoria.

Ele entende tanto API Blueprint quanto OpenAPI. Dredd cresceu junto com o API Blueprint, o formato de descrição baseado em markdown, e mais tarde adicionou suporte a OpenAPI 2 e 3. Se você tem um arquivo Blueprint legado ou um documento Swagger, Dredd pode lê-lo sem uma etapa de conversão.

Hooks agnósticos de linguagem. Quando o loop padrão de solicitação e comparação não é suficiente, você precisa de tokens de autenticação, precisa semear um banco de dados antes de um teste, precisa pular uma transação, Dredd permite que você escreva hooks. O manipulador de hooks é executado em Node por padrão, mas Dredd oferece suporte a protocolo para hooks em Python, Ruby, Go, PHP, Rust e muito mais. Sua equipe escreve a lógica de configuração em uma linguagem que já conhece.

É de código aberto e amigável ao CI. Dredd é instalado com npm install -g dredd, executa como um único comando e sai com um código diferente de zero quando uma validação falha, então qualquer sistema de CI pode bloquear um build com ele. Não há conta SaaS, não há preço por assento, nada para assinar. Para uma equipe que deseja uma verificação de contrato auto-hospedada e roteirizável, isso importa.

Nada disso é encheção de linguiça. Dredd é uma ferramenta sólida com um trabalho claro. A questão é se seu modelo, três artefatos separados e um arquivo de hooks, corresponde à forma como você realmente quer trabalhar.

Onde reside o atrito

Três custos vêm junto com o modelo Dredd, e o quanto eles prejudicam depende da sua configuração.

A especificação é um terceiro artefato que você mantém manualmente. Dredd valida a implementação contra um arquivo de descrição, o que está exatamente correto, mas essa descrição geralmente vive separada de onde você projeta e testa a API. Você edita manualmente um openapi.yaml, mantém seus cenários de teste em outro lugar e mantém o serviço em execução em outro lugar novamente. Dredd verifica dois desses três um contra o outro. Manter a própria especificação precisa ainda é uma tarefa manual, e uma especificação que se afastou silenciosamente da realidade produz uma execução Dredd que é verde e errada.

Hooks são códigos que você escreve e mantém. No momento em que sua API precisa de autenticação, ordenação ou dados de teste, o loop baseado em exemplos deixa de ser suficiente. Você escreve um hooks.js (ou um equivalente em Python ou Ruby), conecta-o através do dredd.yml, e agora você possui uma segunda base de código cujo único trabalho é tornar a primeira testável. Para uma API simples e somente leitura, Dredd é quase sem configuração. Para uma API real com logins e endpoints com estado, o arquivo de hooks cresce, e é um código de cola com outro nome.

A cobertura orientada por exemplos tem lacunas. Dredd testa os exemplos presentes em sua descrição. Se um endpoint tem uma resposta de exemplo documentada, é isso que é verificado. Casos de borda, caminhos de erro e regras de validação que não estão detalhados como exemplos na especificação não são exercitados, a menos que você os adicione, expandindo a especificação ou escrevendo mais hooks. A cobertura é tão boa quanto os exemplos que você mantém, nem um pouco melhor.

O caminho integrado: especificação e testes em um único projeto

Aqui está a aposta diferente que o Apidog faz. A definição da API não é um terceiro arquivo que você sincroniza manualmente; é a fonte da verdade que vive no mesmo projeto que os testes que a exercitam e a validação que controla sua compilação. Altere o esquema, e os testes veem a nova forma. Não há um openapi.yaml separado flutuando em um canto do repositório, e nenhum arquivo de hooks entre a especificação e um teste em funcionamento.

Você projeta ou importa a API uma vez. Apidog lê OpenAPI 2 e 3, importa um documento Swagger e importa coleções Postman com um clique. Os endpoints, os esquemas de solicitação, os esquemas de resposta e os exemplos de respostas, tudo isso fica em um único projeto. Se você já pensa em "spec-first", esta é a mesma disciplina que Dredd encoraja, apenas sem a especificação ser um arquivo solto. A versão mais aprofundada desse fluxo de trabalho está no desenvolvimento de API "spec-first", e se você quiser validar o próprio documento de especificação antes de qualquer execução de teste, validar especificações OpenAPI abrange essa etapa.

Você constrói a validação contra esses esquemas reais. Quando um cenário de teste chama GET /orders/{id}, você afirma a resposta contra o esquema que o Apidog já possui para aquele endpoint, e não contra um exemplo copiado à mão. Essa é a verificação de especificação versus implementação que Dredd executa, com uma diferença: a especificação sendo verificada é o mesmo objeto a partir do qual você projetou a API, então ela não pode se desviar silenciosamente do seu pacote de testes. Isso é teste de contrato sem um terceiro artefato, e se você quiser uma visão mais ampla dessa disciplina, o teste de contrato de API e o teste de contrato bidirecional aprofundam-se ainda mais.

A configuração que Dredd lida com um arquivo de hooks, tokens de autenticação, ordenação, semeadura, você lida com scripts pré e pós-solicitação em JavaScript, que a maioria dos desenvolvedores web já escreve. Não há uma base de código de hooks separada conectada através de um arquivo de configuração. A lógica vive ao lado do teste que ela suporta.

Instalando e executando o CLI do Apidog

O executor é publicado no npm como apidog-cli. Se você tem Node.js, você tem tudo o que precisa:

npm install -g apidog-cli

O binário é apidog, então cada execução começa com apidog run. Para executar um cenário de teste, você passa um token de acesso, o ID do cenário e o ID do ambiente:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Você não digita esses IDs manualmente. Abra o cenário de teste no Apidog, vá para a aba CI/CD, escolha a opção de linha de comando e gere um token de acesso. Apidog constrói o comando completo apidog run para você com os IDs de cenário e ambiente já preenchidos. Copie-o uma vez e parametrize o token a partir daí. Trate o token de acesso como uma senha: armazene-o como um segredo em seu sistema de CI e referencie-o como $APIDOG_ACCESS_TOKEN, da mesma forma que todos os exemplos aqui fazem.

Para executar mais de um cenário, aponte o executor para uma pasta ou um conjunto de testes em vez de um único ID, e escolha seus relatórios:

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

Essa flag -r seleciona os reportadores. Apidog suporta cli para saída legível no terminal, html para um relatório autocontido que você arquiva como um artefato de build, junit para o XML que quase todo painel de CI analisa em uma árvore de aprovação/reprovação, e json para resultados estruturados brutos. Se você deseja um tour mais aprofundado do executor, execute apidog run --help para a lista completa de flags.

Lado a lado

Leia essa tabela honestamente. Se você quer uma ferramenta totalmente auto-hospedada, de código aberto, sem conta e sua equipe se sente confortável em manter um arquivo de hooks, o modelo do Dredd se encaixa perfeitamente e mudar por mudar não lhe trará nenhum benefício. O caso para o caminho integrado é específico: você está cansado de a especificação ser um terceiro arquivo que se desvia, você não quer possuir uma base de código de hooks, ou você quer que o mesmo projeto lide com o design, os testes e a verificação de contrato juntos.

Integrando ao CI

O CLI do Apidog sai com zero em caso de sucesso e diferente de zero em caso de falha, então qualquer sistema de CI pode bloquear um build com ele, exatamente como Dredd. Um job mínimo do GitHub Actions precisa de Node e uma etapa de execução:

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 }}

Essa é a pipeline completa. Um job do Dredd parece semelhante, instala o CLI, executa um comando, mas você também o aponta para seu arquivo de especificação e seu arquivo de hooks, e mantém ambos atualizados. A validação é executada da mesma forma; a diferença é quantos artefatos você mantém para chegar lá.

Se o seu motivo para recorrer ao Dredd era realmente manter uma especificação e um serviço honestos um com o outro, a mesma lógica aparece em outras ferramentas. As equipes encontram isso com o Swagger e o Postman se distanciando, o que o teste impulsionado por OpenAPI contra a divergência entre Swagger e Postman aborda, e as lojas Java o encontram com o Rest Assured, onde a história das alternativas rima: uma ferramenta forte cujo modelo adiciona uma camada que você talvez não queira. Você também pode operar o Apidog a partir do seu editor com a extensão VS Code, se preferir não sair do seu IDE.

Perguntas Frequentes

O Apidog é um substituto direto para uma configuração Dredd? Não, e não pretende ser. Não há um conversor que leia seus arquivos dredd.yml e hooks.js e gere cenários Apidog. Você importa sua especificação OpenAPI e reconstrói a validação no editor visual. A vantagem é que você para de manter um arquivo de hooks e uma especificação solta; o custo é uma reconstrução única. Se você tem um grande e maduro conjunto de testes Dredd que funciona, essa reconstrução é uma decisão real, não um almoço grátis.

O Apidog valida a implementação em tempo real, como Dredd faz? Sim. O CLI dispara requisições reais para o seu serviço em execução e afirma as respostas reais contra os esquemas do seu projeto. Essa é a mesma verificação de especificação versus implementação que Dredd executa. A diferença é que o esquema sendo verificado é aquele a partir do qual você projetou a API, então ele não se desvia dos seus testes.

Ainda consigo lidar com autenticação e configuração de testes da mesma forma que os hooks do Dredd me permitem? Sim. Apidog suporta scripts pré-requisição e pós-requisição em JavaScript, então você pode buscar tokens de autenticação, preencher dados, transformar payloads ou construir asserções dinâmicas em código. A lógica vive no cenário que ela suporta, em vez de em um arquivo de hooks separado configurado.

Dredd faz algo que Apidog não faz? Algumas coisas. Dredd é totalmente auto-hospedado e de código aberto, sem necessidade de conta, e lê API Blueprint, o formato de descrição markdown mais antigo, nativamente. Se uma ferramenta totalmente local, sem conta, ou um arquivo Blueprint legado é central para a sua configuração, pondere isso cuidadosamente antes de mudar.

Qual formato o Apidog lê? OpenAPI 2 e 3, documentos Swagger e coleções Postman, todos importáveis para um único projeto. Se você quiser entender as diferenças de formato primeiro, Swagger versus OpenAPI e a visão geral da especificação OpenAPI ambos os explicam.

Conclusão

Dredd acertou na ideia central: sua descrição de API deve ser algo contra o qual você testa o serviço em execução, e não um documento que se desvia. Se você deseja um CLI auto-hospedado, de código aberto e está feliz em manter um arquivo de especificação e um arquivo de hooks, Dredd é uma escolha sólida e você deve continuar a usá-lo.

O caminho integrado é para o caso em que essa manutenção é a parte que você quer eliminar. Apidog mantém a especificação, os testes e a validação em um único projeto, então o contrato que você verifica é o mesmo do qual você projetou, e ele executa tudo a partir de apidog run sem uma base de código de hooks para gerenciar. Baixe o Apidog e importe seu arquivo OpenAPI existente para ver a verificação de especificação versus implementação ser executada a partir de um único comando.