Como Criei o pacote npm json-to-mock-api - minha solução para mocks de API simples, organizados e poderosos · rubensflinco

Olá, pessoal! Aqui é o Rubens Flinco, desenvolvedor com mais de 10 anos de estrada, e hoje quero compartilhar com vocês a história de como criei o json-to-mock-api, uma lib para mock de APIs que nasceu da minha frustração com outras ferramentas que existem por aí.

O Problema: mocks confusos e limitados

Trabalhando com desenvolvimento web, especialmente em projetos que envolvem APIs REST, sempre precisei de uma solução para simular endpoints rapidamente durante o desenvolvimento frontend ou para testes.

Porém, todas as bibliotecas que eu testava tinham vários problemas que me incomodavam bastante:

📁 Organização ruim dos mocks: a maioria das libs usa um único arquivo JSON gigante ou arquivos separados sem um sistema claro para organização em pastas. Isso vira uma bagunça quando a API cresce e fica difícil manter.
📝 Falta de documentação automática: ter uma documentação interativa do mock, que permita testar endpoints direto no navegador, era quase impossível ou exigia muito setup.
🔀 Rotas engessadas: muitas libs geram as rotas automaticamente baseadas no nome dos arquivos ou na estrutura de pastas, o que limita a flexibilidade de criar rotas personalizadas, com parâmetros dinâmicos na URL (como /users/:id) ou caminhos complexos.

A solução: criar o json-to-mock-api

Diante dessas dificuldades, decidi construir minha própria ferramenta, que tivesse exatamente o que eu precisava - e que pudesse ajudar outros desenvolvedores também.

O json-to-mock-api nasceu com algumas premissas muito claras:

🗂️ Sistema completo de pastas: para organizar os mocks em vários arquivos e pastas, sem perder a flexibilidade.
📚 Documentação Swagger automática: ao rodar o mock, ele gera uma documentação interativa com Swagger UI, onde você pode explorar e testar os endpoints sem precisar de ferramentas extras.
🔄 Endpoints definidos no JSON: o usuário define no arquivo JSON os paths e métodos HTTP exatamente como quiser, incluindo parâmetros dinâmicos (:id, :slug), podendo criar qualquer rota customizada, desde a raiz / até rotas mais complexas.
💻 Simples de usar: roda direto pelo npx, sem necessidade de instalar globalmente, e com configuração mínima.

Como funciona na prática
Você cria arquivos JSON com uma chave "endpoints" e dentro dela define suas rotas com os métodos HTTP, corpos de resposta, headers, cookies, tudo muito intuitivo.

Por exemplo:

{
  "endpoints": {
    "users": {
      "GET": {
        "body": [{ "id": 1, "name": "Rubens" }]
      },
      "POST": {
        "body": { "id": 2, "name": "Novo Usuário" }
      }
    },
    "users/:id": {
      "GET": {
        "body": { "id": 1, "name": "Rubens" }
      }
    }
  }
}

Além disso, você pode usar pastas para dividir seus arquivos, o que deixa o projeto limpo e fácil de escalar.

O resultado que me deixou feliz

O json-to-mock-api hoje me permite criar mocks robustos, organizados e com documentação automática em minutos. É uma ferramenta que uso em todos os meus projetos e ensino nas minhas aulas.

Estou muito feliz em compartilhar isso com a comunidade e espero que facilite o dia a dia de muitos desenvolvedores mundo afora, seja no Brasil ou no exterior.

Como você começa a usar?

É simples:

npx json-to-mock-api -f ./mock-api
Tudo o que você precisa é criar seus arquivos JSON e pronto, seu mock estará rodando com docs acessíveis no navegador.

Se quiser conhecer mais, acesse o GitHub e npm:

Documentação: https://jsont-to-mock-api.fdoma.in
GitHub: https://github.com/rubensflinco/json-to-mock-api
npm: https://www.npmjs.com/package/json-to-mock-api

Obrigado por ler até aqui! Me conta o que achou, dúvidas ou ideias de melhorias são super bem-vindas! 🚀