Você precisa de uma API falsa para desenvolver. O backend não está pronto, ou o serviço de terceiros tem limite de taxa, ou você simplesmente quer que seus testes rodem sem atingir um servidor real. A resposta usual é um mock. A questão é como configurá-lo.
Você pode clicar em uma interface gráfica para definir rotas e respostas pré-definidas. Isso serve uma vez. Mas um mock que você constrói manualmente em um aplicativo de desktop é difícil de reproduzir, difícil de versionar e impossível para CI ou um agente de codificação de IA recriar por conta própria. Um mock que você define pela linha de comando é diferente. É um comando em um script, um passo em um pipeline, uma linha que um agente pode executar. O que você digita, uma máquina também pode digitar.
Este guia aborda duas rotas. Primeiro, o caminho geral de código aberto: servidores mock de um único binário que você executa diretamente de um arquivo, de modo que uma especificação ou um arquivo JSON se torna um endpoint ativo em um único comando. Em seguida, o caminho da CLI do Apidog, que funciona de forma diferente e vale a pena entender em seus próprios termos. Se você quer primeiro o panorama das opções, nossa compilação das melhores ferramentas de mock de API e o guia de ferramentas de mock de API REST oferecem uma visão mais ampla.
A rota geral: execute um servidor mock a partir de um arquivo
O mock clássico de CLI é um pequeno binário que você aponta para um arquivo. Dê a ele uma especificação ou um arquivo de dados, e ele serve um endpoint HTTP real em uma porta local. Sem projeto, sem login, sem conta. Essas ferramentas fazem uma coisa: transformar um arquivo em uma API falsa que você pode chamar. Três delas cobrem quase todos os casos.
Prism: sirva uma especificação OpenAPI
Se você já tem um arquivo OpenAPI, Prism da Stoplight é o mock de menor esforço que você pode executar. Ele lê seus paths, exemplos e schemas, e então serve respostas que correspondem ao contrato.
npx @stoplight/prism-cli mock ./openapi.yaml
Isso inicia um servidor em http://127.0.0.1:4010 com cada operação da sua especificação conectada. O Prism retorna o example que você definiu para uma resposta, ou gera um válido aleatório a partir do schema se você o omitiu. Ele também valida as requisições de entrada contra a especificação, então uma chamada malformada recebe um 422 adequado em vez de um passe silencioso. Chame-o para verificar se está ativo:
curl http://127.0.0.1:4010/orders/123
O Prism é sem estado, então um POST não persiste nada. Esse é o objetivo quando você quer que o mock seja honesto com o contrato. Para uma instalação global, execute npm install -g @stoplight/prism-cli e remova o npx.
Mockoon CLI: execute um arquivo de dados sem interface gráfica
Mockoon CLI executa um mock a partir de um arquivo de dados, seja um que você exportou do aplicativo de desktop Mockoon gratuito ou uma especificação OpenAPI simples. O aplicativo de desktop permite construir rotas visualmente; a CLI executa o mesmo ambiente sem interface gráfica em CI ou em um servidor.
npx @mockoon/cli start --data ./env.json
Aponte --data para um arquivo de ambiente Mockoon ou um arquivo JSON/YAML OpenAPI e ele serve imediatamente, usando a porta 3000 por padrão. Adicione --port para alterá-la. Se o arquivo de dados veio de uma versão mais antiga do Mockoon, a CLI o migra na memória sem tocar no original. Instale-o globalmente com npm install -g @mockoon/cli para ter um comando mockoon-cli persistente. Isso é uma boa opção quando você deseja rotas mais ricas e personalizadas do que uma especificação simples oferece e ainda quer que elas funcionem sem uma interface gráfica. Um servidor mock leve para uma API RESTful geralmente se encaixa aqui.
json-server: simule uma API REST a partir de JSON
Quando você ainda não tem uma especificação, o json-server é o caminho mais rápido. Você escreve um arquivo JSON simples descrevendo seus dados, e ele constrói uma API REST completa em torno disso.
npx json-server db.json
Dado um db.json com um array posts, isso serve http://localhost:3000/posts com GET, POST, PUT, PATCH e DELETE reais. Um POST realmente adiciona um registro e o escreve de volta no arquivo, então você obtém comportamento com estado gratuitamente, o que o Prism não lhe dará. Você também obtém filtragem, ordenação e paginação através de parâmetros de consulta. Instale globalmente com npm install -g json-server se você quiser que ele esteja sempre em seu PATH.
Essa é a rota aberta. Cada ferramenta é um único binário, executa a partir de um arquivo e não precisa de mais nada. A desvantagem é que cada uma é uma ilha. O mock vive separadamente do seu design real, de seus testes e de sua documentação, e você mantém os arquivos e os processos em execução sincronizados por conta própria. Se você precisa de correspondência exata de requisições ou replay, MockServer e WireMock vão mais fundo, ao custo de um ambiente de execução Java.
A rota da CLI do Apidog: importe a especificação, crie scripts para as expectativas
O Apidog simula de forma diferente, e entender isso corretamente evita confusão. A CLI do apidog não inicia um servidor mock local a partir de um arquivo. Não existe apidog mock ./openapi.yaml. Em vez disso, o Apidog hospeda o mock para você, e a CLI é como você o alimenta com uma especificação e scripts de respostas personalizadas.
Uma nota honesta primeiro. O Apidog não é código aberto; é um produto comercial com um nível gratuito. O que esse nível gratuito mais a CLI oferece é um projeto integrado, de modo que o mock, o design e os testes compartilham uma única fonte de verdade, em vez de três arquivos e três processos separados. Se um mock descartável de um único arquivo é tudo o que você precisa, uma ferramenta mais leve vence. Se seu mock deve acompanhar sua API real à medida que ela muda, continue lendo.
Instale e autentique primeiro (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>
Importe uma especificação para obter mocks inteligentes hospedados
O primeiro passo é colocar sua API em um projeto. Importe um arquivo OpenAPI, e o Apidog gera um URL de mock para cada endpoint automaticamente.
apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
É aqui que o Apidog difere do Prism e do json-server. Você não executa um servidor; a importação lhe dá um mock inteligente hospedado para cada operação. O mock inteligente lê os tipos e nomes dos campos do seu esquema, de modo que um campo email retorna um email plausível e um createdAt retorna um carimbo de data/hora com aparência real, não uma string aleatória. O apidog import também aceita formatos Swagger 2.0, Postman e Apidog, então uma definição existente se torna mocks ativos em um comando.
Crie scripts de respostas personalizadas com apidog mock
Mocks gerados automaticamente cobrem o caso comum. Quando você precisa de uma resposta específica para uma requisição específica, digamos um 200 para um ID de usuário e um 404 para outro, você adiciona uma expectativa de mock. É isso que o grupo de comandos apidog mock gerencia, e é um CRUD nessas expectativas, não um servidor que você inicia.
apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
A listagem retorna JSON estruturado, então você pode passá-lo por jq para encontrar o ID de uma expectativa e alimentá-lo no próximo comando. Para ler, alterar ou remover uma:
apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Os subcomandos create e update aceitam um --file descrevendo a expectativa. Entenda o formato antes de escrevê-lo, abordado a seguir.
Valide o arquivo de expectativa antes de escrevê-lo
Não adivinhe o JSON. A CLI envia um schema para cada escrita, então você obtém o formato, preenche-o e valida antes da escrita real. Uma expectativa malformada falha rapidamente em vez de passar silenciosamente.
apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Obtenha o schema, escreva seu mock.json para corresponder, valide-o e então crie. Se a validação retornar um código de saída diferente de zero, o pipeline para antes que um arquivo inválido chegue ao seu projeto. Execute os mesmos três passos para atualizações com a chave de schema mock-update. Todo comando retorna JSON com um bloco agentHints.nextSteps que informa a você, ou a um agente, o que executar em seguida, o que torna esse fluxo utilizável por ferramentas de codificação de IA e não apenas por humanos. O guia completo da CLI do Apidog mapeia o restante dos grupos de comando.
Integrando-o no CI
Ambas as rotas se encaixam em um pipeline porque cada comando tem um código de saída e uma saída de texto. Um mock baseado em servidor e um teste de integração no mesmo trabalho podem parecer com isto:
# inicie o Prism em segundo plano, depois execute os testes contra ele
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!
npm test
kill $PRISM_PID
O fluxo do Apidog é diferente na forma: não há processo local para iniciar e parar, porque o mock é hospedado. Você valida e aplica as expectativas como um passo de configuração, e seus testes atingem o URL do mock hospedado diretamente.
# garanta que a expectativa está bem formada, então aplique-a
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
De qualquer forma, ninguém clica em um botão. Essa é a principal razão para simular a partir da CLI: uma equipe com foco na especificação, um trabalho de CI e um agente de IA podem configurar a mesma API falsa a partir dos mesmos comandos.
Armadilhas comuns
Esperando que apidog mock inicie um servidor. Não vai. Não há apidog mock start, apidog mock serve ou apidog mock ./file.yaml. Você apidog import uma especificação para obter mocks hospedados, e apidog mock gerencia as expectativas personalizadas sobre eles. Se você quer um processo local que você lança a partir de um arquivo, isso é Prism, Mockoon CLI ou json-server.
Pulando a etapa de esquema em uma escrita. apidog mock create e update aceitam um --file, e um formato incorreto falha ou escreve algo que você não pretendia. Sempre execute cli-schema get e cli-schema validate primeiro. São dois comandos extras e economizam uma sessão de depuração.
Prism parece vazio porque sua especificação é incompleta. O mock do Prism é tão bom quanto seus exemplos. Se uma resposta não tem example e um esquema vago, você obtém dados vagos. Adicione exemplos à especificação e o mock ficará mais preciso.
Expectativas com estado de uma ferramenta sem estado. Os mocks de contrato do Prism e do Apidog não persistem gravações. Se você precisa que um POST e depois um GET retornem o novo registro, use o json-server ou uma expectativa do Apidog que retorna o formato desejado.
Conclusão
Simular a partir da CLI transforma uma tarefa de muitos cliques em comandos que você pode roteirizar, revisar e entregar ao CI ou a um agente. A rota aberta oferece servidores de único binário que você executa a partir de um arquivo: Prism para uma especificação OpenAPI, Mockoon CLI para um arquivo de dados sem interface gráfica, json-server para uma API REST instantânea a partir de JSON. A rota do Apidog funciona de outra forma; você importa uma especificação uma vez para obter mocks inteligentes hospedados, então roteiriza respostas personalizadas com apidog mock e a guarda de validação cli-schema.
Escolha com base no que você já tem e onde o mock precisa residir. Se você quer um servidor descartável a partir de um arquivo, as ferramentas abertas são perfeitas. Se você quer que o mock esteja em sincronia com seu design e testes em um único projeto, baixe o Apidog, instale a CLI e configure seus mocks sem tocar no mouse.