OpenAPI → Postman Collection Converter

When to Use

Use this skill when you need convert OpenAPI 3.x or Swagger 2.0 specs (YAML or JSON) into complete, import-ready Postman Collection v2.1 JSON files. Use this skill whenever the user provides or references an OpenAPI spec, Swagger file, openapi.yaml, swagger.json, or uses phrases like "convert my OpenAPI spec",...

Converts OpenAPI 3.x or Swagger 2.0 specs into a valid Postman Collection v2.1.

Step 1 — Detect & Validate Input

Identify the spec version from the input:

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

If the input is truncated or partial, convert what's available and note missing sections.

Step 2 — Extraction Mapping

OpenAPI 3 → Postman

Swagger 2 → Postman

Step 3 — Generate Example Bodies

For each request with a requestBody or body parameter, generate a realistic example JSON body from the schema:

• Use property names as keys
• Infer sensible example values from type + format (e.g., "email" format → "user@example.com", "date-time" → "2024-01-15T10:30:00Z")
• For $ref schemas, resolve them inline

Step 4 — Auth Handling

Map security schemes to Postman auth:

Apply auth at collection level if all endpoints share the same scheme. Override at request level for exceptions.

Step 5 — Build Collection JSON

Use the standard v2.1 structure (same schema as postman-collection-generator skill).

Key differences for spec-converted collections:

• Always group by tags into folders
• Include description field on each request from operationId + summary + description
• Add saved example responses where responses are defined in the spec

"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> }
  }
]

Step 6 — Environment File

Extract all variables into a companion environment:

• base_url from servers[0].url or host + basePath
• token, api_key, username, password as empty placeholders
• Any server variables from servers[0].variables

Step 7 — Output

1. collection.json — Full Postman Collection v2.1
2. environment.json — Matching environment file
3. Conversion summary: number of endpoints converted, folders created, auth type detected, any fields skipped or approximated
4. Import instructions

Edge Cases

• $ref chains: Resolve all $ref pointers inline before mapping
• allOf / oneOf / anyOf: Use the first/primary schema for body generation; note alternatives in description
• Path parameters: Convert {param} to :param in URL path AND add to variable array in url object
• Multiple content types: Prefer application/json; note others in request description
• No operationId: Generate name from METHOD /path (e.g., GET /users/{id} → Get User by ID)

Quality Checklist

• Every paths entry produces at least one request
• Path params use :param format in Postman URL
• All $ref resolved — no raw $ref strings in output

…