Conversor de OpenAPI para Coleção Postman

Quando Usar

Use esta habilidade quando precisar converter especificações OpenAPI 3.x ou Swagger 2.0 (YAML ou JSON) em arquivos JSON completos da Coleção Postman v2.1, prontos para importação. Use esta habilidade sempre que o usuário fornecer ou referenciar uma especificação OpenAPI, arquivo Swagger, openapi.yaml, swagger.json, ou usar frases como "converter minha especificação OpenAPI",...

Converte especificações OpenAPI 3.x ou Swagger 2.0 em uma Coleção Postman v2.1 válida.

Passo 1 — Detectar e Validar Entrada

Identifique a versão da especificação a partir da entrada:

• openapi: 3.x.x → OpenAPI 3
• swagger: "2.0" → Swagger 2

Se a entrada estiver truncada ou parcial, converta o que estiver disponível e anote as seções ausentes.

Passo 2 — Mapeamento de Extração

OpenAPI 3 → Postman

Swagger 2 → Postman

Passo 3 — Gerar Corpos de Exemplo

Para cada requisição com um parâmetro requestBody ou body, gere um corpo JSON de exemplo realista a partir do esquema:

• Use nomes de propriedade como chaves
• Infira valores de exemplo sensatos a partir do tipo + formato (por exemplo, formato "email" → "user@example.com", "date-time" → "2024-01-15T10:30:00Z")
• Para esquemas $ref, resolva-os inline

Passo 4 — Tratamento de Autenticação

Mapeie esquemas de segurança para autenticação Postman:

Aplique a autenticação no nível da coleção se todos os endpoints compartilharem o mesmo esquema. Substitua no nível da requisição para exceções.

Passo 5 — Construir JSON da Coleção

Use a estrutura padrão v2.1 (mesmo esquema da habilidade postman-collection-generator).

Principais diferenças para coleções convertidas de especificações:

• Sempre agrupe por tags em pastas
• Inclua o campo description em cada requisição a partir de operationId + summary + description
• Adicione respostas de exemplo salvas onde responses são definidas na especificação

"response": [
  {
    "name": "200 OK",
    "status": "OK",
    "code": 200,
    "header": [{ "key": "Content-Type", "value": "application/json" }],
    "body": "{ \"id\": 1, \"name\": \"example\" }",
    "originalRequest": { <copy of the request> }
  }
]

Passo 6 — Arquivo de Ambiente

Extraia todas as variáveis para um ambiente complementar:

• base_url de servers[0].url ou host + basePath
• token, api_key, username, password como placeholders vazios
• Quaisquer variáveis de servidor de servers[0].variables

Passo 7 — Saída

1. collection.json — Coleção Postman v2.1 completa
2. environment.json — Arquivo de ambiente correspondente
3. Resumo da conversão: número de endpoints convertidos, pastas criadas, tipo de autenticação detectado, quaisquer campos ignorados ou aproximados
4. Instruções de importação

Casos de Borda

• Cadeias $ref: Resolva todos os ponteiros $ref inline antes do mapeamento
• allOf / oneOf / anyOf: Use o primeiro/primário esquema para a geração do corpo; anote alternativas na descrição
• Parâmetros de caminho: Converta {param} para :param no caminho da URL E adicione ao array variable no objeto url
• Múltiplos tipos de conteúdo: Prefira application/json; anote outros na descrição da requisição
• Sem operationId: Gere o nome a partir de METHOD /path (por exemplo, GET /users/{id} → Get User by ID)

Checklist de Qualidade

• Cada entrada paths produz pelo menos uma requisição
• Parâmetros de caminho usam o formato :param na URL do Postman
• Todos os $ref resolvidos — sem strings $ref brutas na saída

…