| name | postman-collection-generator |
| version | 1.0.0 |
| description | Gera colecoes Postman a partir de specs OpenAPI/Swagger, codigo de handler ou documentacao de API. Use quando precisar de colecao testavel para endpoints REST. Nao use para testar endpoints diretamente — gera apenas o artefato de colecao. |
Postman Collection Generator
Procedimentos
Etapa 1: Identificar fonte de entrada
- Confirmar que o contrato de carga base definido em
AGENTS.md foi cumprido.
- Verificar se ha arquivo OpenAPI/Swagger (
.yaml, .json) disponível.
- Se nao houver spec, ler handlers HTTP e derivar endpoints, metodos, parametros e schemas.
- Listar endpoints a incluir na colecao.
Etapa 2: Estruturar a colecao
- Criar estrutura de pastas por recurso ou modulo (ex:
Users, Orders).
- Para cada endpoint: metodo, URL com variaveis
{{base_url}}, headers, body exemplo.
- Adicionar variaveis de ambiente:
base_url, token, api_version.
- Incluir testes basicos por request: status code, estrutura da resposta.
Etapa 3: Gerar o JSON Postman Collection v2.1
- Gerar JSON compatível com Postman Collection Format 2.1.
- Usar
{{variavel}} para valores que variam por ambiente.
- Incluir exemplos de request e response para cada endpoint.
- Salvar em
docs/postman/<collection-name>.postman_collection.json.
Etapa 4: Documentar variaveis de ambiente
- Gerar arquivo
<collection-name>.postman_environment.json com variaveis e valores de exemplo.
- Documentar quais variaveis sao obrigatorias antes de executar a colecao.
Tratamento de Erros
- Se a spec OpenAPI estiver incompleta, gerar a colecao com o que existir e listar endpoints faltantes.
- Nao incluir tokens ou senhas reais nos valores de exemplo — usar placeholders descritivos.
- Se endpoints exigirem autenticacao complexa (OAuth2, MTLS), documentar o fluxo sem implementar.
