VTEX IO Postman Generator

Gerador automático de Postman Collections para aplicações VTEX IO, inspirado no php artisan postman:generate.

📋 Descrição

Este pacote analisa automaticamente os arquivos service.json e index.ts de uma aplicação VTEX IO e gera uma collection do Postman com todas as rotas, métodos HTTP e parâmetros configurados.

🚀 Instalação

Opção 1: NPX (Sem Instalação - Recomendado)

# Uso direto sem instalar
npx @vtex-io/postman-generator

# Com opções
npx @vtex-io/postman-generator --account mystore --workspace dev

Opção 2: Instalação Global

# NPM
npm install -g ./node/postman-generator

# Yarn
yarn global add ./node/postman-generator

# Usar
vtex-postman
vtex-postman-generate

Opção 3: Como Dependência do Projeto

npm install --save-dev ./node/postman-generator

Adicione ao package.json:

{
  "scripts": {
    "postman:generate": "vtex-postman"
  }
}

📖 Mais detalhes: Veja INSTALL.md para todos os métodos de instalação

💻 Uso

NPX (Mais Fácil)

# No diretório do projeto VTEX IO
npx @vtex-io/postman-generator

# Com opções
npx @vtex-io/postman-generator --account mystore --workspace dev --output api.json

Instalação Global

# Depois de instalar globalmente
vtex-postman
vtex-postman --account mystore --workspace dev

# Comando alternativo
vtex-postman-generate

Via NPM Scripts

# Se já está configurado no package.json
npm run postman:generate
yarn postman:generate

Opções disponíveis

• --dir, -d: Diretório raiz do projeto VTEX IO (padrão: diretório atual)
• --output, -o: Nome do arquivo de saída (padrão: postman-collection.json)
• --account, -a: Nome da account VTEX (padrão: {{account}})
• --workspace, -w: Nome do workspace VTEX (padrão: {{workspace}})
• --environment, -e: URL base do ambiente (padrão: myvtex.com)

📦 Estrutura gerada

A collection do Postman será gerada com:

• ✅ Todas as rotas definidas em service.json
• ✅ Métodos HTTP (GET, POST, PUT, PATCH, DELETE, OPTIONS)
• ✅ Parâmetros de rota (:id, :email, etc.)
• ✅ Variáveis de ambiente para account e workspace
• ✅ Organização por grupos lógicos
• ✅ Headers padrão configurados

🔧 Exemplo de saída

{
  "info": {
    "name": "VTEX IO - Main Account API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Organizations",
      "item": [
        {
          "name": "Get Organizations by Email V2",
          "request": {
            "method": "GET",
            "url": "https://{{account}}.{{environment}}/{{workspace}}/_v/main-account/organizations/v2/:email"
          }
        }
      ]
    }
  ]
}

🛠️ Como funciona

1. Lê o arquivo service.json: Extrai todas as rotas configuradas com seus paths
2. Analisa o arquivo index.ts: Identifica os métodos HTTP disponíveis para cada rota
3. Detecta parâmetros: Identifica parâmetros de rota (:param), query strings e body
4. Gera a collection: Cria um arquivo JSON compatível com Postman Collection v2.1

📝 Notas

• O gerador assume a estrutura padrão de projetos VTEX IO
• Parâmetros de rota são convertidos em variáveis do Postman
• Headers de autenticação devem ser configurados manualmente após importar

🤝 Contribuindo

Sinta-se à vontade para abrir issues ou pull requests com melhorias!

📄 Licença

MIT