DEV Community

Cover image for Como mockar APIs via CLI
Lucas
Lucas

Posted on • Originally published at apidog.com

Como mockar APIs via CLI

Você precisa de uma API falsa para desenvolver. O backend pode não estar pronto, um serviço de terceiros pode ter limite de taxa, ou seus testes precisam rodar sem atingir um servidor real. A solução usual é um mock — a questão é como configurá-lo de forma reproduzível.

Experimente o Apidog hoje

Você pode definir rotas e respostas em uma interface gráfica. Isso funciona para um teste pontual, mas um mock criado manualmente em um aplicativo desktop é difícil de reproduzir, versionar e executar no CI. Também não é algo que um agente de codificação de IA consegue recriar de forma confiável.

Um mock definido pela CLI é diferente: ele vira um comando em um script, uma etapa do pipeline e uma instrução que humanos e máquinas podem executar da mesma forma.

Este guia aborda duas abordagens:

  1. Ferramentas open source baseadas em arquivo, que iniciam um servidor mock local com um único comando.
  2. CLI do Apidog, que importa sua especificação e gerencia mocks hospedados e expectativas personalizadas.

Para comparar opções antes de começar, consulte as compilações das melhores ferramentas de mock de API e de ferramentas de mock de API REST.

A rota geral: execute um servidor mock a partir de um arquivo

O padrão clássico de mock via CLI é simples: você aponta um binário para um arquivo de especificação ou dados, e ele expõe endpoints HTTP em uma porta local.

Essa abordagem não exige projeto, login ou conta. Na prática, ela transforma um arquivo versionado em uma API falsa executável.

Prism: sirva uma especificação OpenAPI

Se você já tem um arquivo OpenAPI, o Prism da Stoplight é uma opção de baixo esforço. Ele lê paths, exemplos e schemas da especificação e responde de acordo com o contrato.

npx @stoplight/prism-cli mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

O comando inicia o servidor em http://127.0.0.1:4010.

Teste uma operação definida na sua especificação:

curl http://127.0.0.1:4010/orders/123
Enter fullscreen mode Exit fullscreen mode

O Prism retorna:

  • O example definido na resposta, quando existir.
  • Dados gerados a partir do schema, quando não houver exemplo.
  • Um erro 422 para requisições que não correspondem ao contrato.

Para instalar globalmente:

npm install -g @stoplight/prism-cli
Enter fullscreen mode Exit fullscreen mode

Depois disso, remova o npx dos comandos.

O Prism não mantém estado. Um POST não persiste dados para um GET posterior. Isso é útil quando seu objetivo é validar o contrato, não simular um banco de dados.

Mockoon CLI: execute um arquivo de dados sem interface gráfica

O Mockoon CLI inicia um mock a partir de um arquivo de ambiente exportado pelo Mockoon Desktop ou de uma especificação OpenAPI JSON/YAML.

npx @mockoon/cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

Por padrão, o servidor usa a porta 3000. Para definir outra porta:

npx @mockoon/cli start --data ./env.json --port 8080
Enter fullscreen mode Exit fullscreen mode

Use essa opção quando precisar de rotas e respostas mais personalizadas do que uma especificação OpenAPI simples oferece, mas ainda quiser executar tudo sem interface gráfica.

Para instalação global:

npm install -g @mockoon/cli
Enter fullscreen mode Exit fullscreen mode

Isso disponibiliza o comando mockoon-cli no seu PATH.

Um servidor mock leve para uma API RESTful normalmente se encaixa nesse cenário.

json-server: simule uma API REST a partir de JSON

Quando você ainda não tem uma especificação, o json-server é uma das formas mais rápidas de criar uma API REST simulada.

Crie um db.json:

{
  "posts": [
    {
      "id": 1,
      "title": "Primeiro post"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Inicie o servidor:

npx json-server db.json
Enter fullscreen mode Exit fullscreen mode

Agora você terá endpoints como:

GET    http://localhost:3000/posts
POST   http://localhost:3000/posts
PUT    http://localhost:3000/posts/1
PATCH  http://localhost:3000/posts/1
DELETE http://localhost:3000/posts/1
Enter fullscreen mode Exit fullscreen mode

Ao contrário do Prism, o json-server mantém estado: um POST adiciona registros e grava a alteração de volta no arquivo JSON. Ele também oferece filtragem, ordenação e paginação por parâmetros de consulta.

Para instalação global:

npm install -g json-server
Enter fullscreen mode Exit fullscreen mode

Quando usar ferramentas baseadas em arquivo

A rota open source funciona bem quando você quer um mock local, descartável e fácil de subir em qualquer ambiente.

A limitação é que cada ferramenta opera de forma isolada: mock, design, testes e documentação podem ficar em arquivos e processos separados. Você precisa mantê-los sincronizados.

Se precisar de correspondência exata de requisições ou replay, alternativas como MockServer e WireMock oferecem mais recursos, mas exigem um ambiente de execução Java.

A rota da CLI do Apidog: importe a especificação e crie scripts para as expectativas

O Apidog trabalha de forma diferente das ferramentas que iniciam um processo local.

A CLI apidog não inicia um servidor mock local a partir de um arquivo. Não existe um comando como:

apidog mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Em vez disso, o Apidog hospeda o mock. A CLI serve para importar especificações e criar ou gerenciar respostas personalizadas.

O Apidog não é open source; é um produto comercial com nível gratuito. Sua proposta é manter mock, design e testes no mesmo projeto, em vez de distribuir essas responsabilidades entre vários arquivos e processos.

Se você precisa apenas de um servidor descartável a partir de um arquivo, Prism, Mockoon CLI ou json-server provavelmente são opções mais leves. Se o mock precisa evoluir junto com a API, continue com o fluxo abaixo.

Instale a CLI e autentique-se. O guia de instalação da CLI do Apidog cobre a configuração do token.

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Importe uma especificação para obter mocks inteligentes hospedados

O primeiro passo é importar sua API para um projeto do Apidog.

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Após a importação, o Apidog gera URLs de mock hospedadas para as operações da especificação.

Esse fluxo difere do Prism e do json-server:

  • Você não inicia nem encerra um servidor local.
  • O mock é hospedado.
  • As respostas são geradas com base nos tipos e nomes dos campos do schema.

Por exemplo, um campo email pode retornar um email plausível, enquanto createdAt pode retornar um valor com formato de data e hora.

O comando apidog import também aceita formatos Swagger 2.0, Postman e Apidog, permitindo transformar uma definição existente em mocks ativos em um comando.

Crie respostas personalizadas com apidog mock

Mocks gerados automaticamente cobrem o caso comum. Para controlar uma resposta específica — por exemplo, retornar 200 para um ID e 404 para outro — crie uma expectativa de mock.

O grupo apidog mock gerencia essas expectativas. Ele não inicia um servidor.

Comece explorando os comandos disponíveis:

apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Enter fullscreen mode Exit fullscreen mode

A saída é JSON estruturado, então você pode usar jq para localizar IDs e encadear operações em scripts.

Para consultar, alterar ou remover uma expectativa:

apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Os comandos create e update aceitam um arquivo com --file. Antes de criar esse arquivo, obtenha e valide o schema esperado.

Valide o arquivo de expectativa antes de gravá-lo

Não adivinhe a estrutura de mock.json. A CLI fornece schemas para operações de escrita.

Use este fluxo:

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

A sequência recomendada é:

  1. Obter o schema com cli-schema get.
  2. Criar o arquivo mock.json conforme o schema.
  3. Validar com cli-schema validate.
  4. Criar a expectativa com apidog mock create.

Para atualizações, use a chave de schema mock-update.

Se a validação retornar um código de saída diferente de zero, o pipeline falha antes de gravar uma configuração inválida no projeto.

Os comandos retornam JSON com agentHints.nextSteps, indicando próximos passos que podem ser usados tanto por desenvolvedores quanto por agentes de codificação de IA. Consulte o guia completo da CLI do Apidog para os demais grupos de comandos.

Integrando no CI

As duas abordagens funcionam em pipelines porque os comandos retornam códigos de saída e saída textual.

Executando Prism no pipeline

Inicie o servidor em segundo plano, rode os testes e encerre o processo:

# Inicie o Prism em segundo plano e execute os testes contra ele
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

npm test

kill $PRISM_PID
Enter fullscreen mode Exit fullscreen mode

Aplicando expectativas do Apidog no pipeline

No fluxo do Apidog, não existe um processo local para iniciar ou encerrar. O mock é hospedado; o pipeline valida e aplica as expectativas antes dos testes.

# Valide a expectativa e aplique-a ao projeto
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Depois disso, seus testes podem chamar diretamente a URL do mock hospedado.

O ganho principal da CLI é eliminar cliques manuais: uma equipe orientada à especificação, um job de CI e um agente de IA podem configurar a mesma API falsa usando os mesmos comandos.

Armadilhas comuns

Esperar que apidog mock inicie um servidor

Não inicia. Não existem comandos como:

apidog mock start
apidog mock serve
apidog mock ./file.yaml
Enter fullscreen mode Exit fullscreen mode

Use apidog import para importar a especificação e obter mocks hospedados. Use apidog mock para gerenciar expectativas personalizadas nesses mocks.

Se você precisa iniciar um processo local a partir de um arquivo, use Prism, Mockoon CLI ou json-server.

Pular a validação do schema

apidog mock create e apidog mock update aceitam --file, mas um arquivo com formato incorreto pode falhar ou produzir uma expectativa diferente da pretendida.

Execute sempre:

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

São dois comandos adicionais que evitam sessões de depuração desnecessárias.

Obter respostas vagas do Prism

O Prism só pode gerar respostas tão precisas quanto sua especificação permite.

Se uma resposta não define example e usa schemas vagos, o mock também será vago. Adicione exemplos explícitos ao OpenAPI para obter respostas mais úteis e previsíveis.

Esperar estado em uma ferramenta sem estado

Mocks de contrato do Prism e do Apidog não persistem gravações.

Se você precisa que um POST seja seguido por um GET que retorna o novo registro, use o json-server ou configure uma expectativa do Apidog que retorne a estrutura desejada.

Conclusão

Mocks via CLI transformam uma tarefa manual em comandos que você pode versionar, revisar, automatizar e executar no CI.

A rota open source oferece servidores executados a partir de arquivos:

  • Prism para especificações OpenAPI.
  • Mockoon CLI para arquivos de dados e mocks sem interface gráfica.
  • json-server para APIs REST instantâneas a partir de JSON.

A rota do Apidog funciona de outra forma: você importa uma especificação para gerar mocks inteligentes hospedados e usa apidog mock com cli-schema para criar e validar expectativas personalizadas.

Escolha com base no que você já possui e onde o mock deve viver. Para um servidor local descartável, as ferramentas open source são diretas. Para manter mock, design e testes sincronizados em um único projeto, baixe o Apidog, instale a CLI e configure seus mocks sem depender de uma interface gráfica.

Top comments (0)