postman-collection-generator

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

1. Confirmar que o contrato de carga base definido em AGENTS.md foi cumprido.
2. Verificar se ha arquivo OpenAPI/Swagger (.yaml, .json) disponível.
3. Se nao houver spec, ler handlers HTTP e derivar endpoints, metodos, parametros e schemas.
4. Listar endpoints a incluir na colecao.

Etapa 2: Estruturar a colecao

1. Criar estrutura de pastas por recurso ou modulo (ex: Users, Orders).
2. Para cada endpoint: metodo, URL com variaveis {{base_url}}, headers, body exemplo.
3. Adicionar variaveis de ambiente: base_url, token, api_version.
4. Incluir testes basicos por request: status code, estrutura da resposta.

Etapa 3: Gerar o JSON Postman Collection v2.1

1. Gerar JSON compatível com Postman Collection Format 2.1.
2. Usar {{variavel}} para valores que variam por ambiente.
3. Incluir exemplos de request e response para cada endpoint.
4. Salvar em docs/postman/<collection-name>.postman_collection.json.

Etapa 4: Documentar variaveis de ambiente

1. Gerar arquivo <collection-name>.postman_environment.json com variaveis e valores de exemplo.
2. 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.