postman-openapi-converter

OpenAPI → Postman Collection Converter

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

| OpenAPI field | Postman mapping | |---|---| | info.title | Collection name | | info.description | Collection description | | servers[0].url | {{base_url}} variable | | paths.<path>.<method> | One request item per operation | | operationId or summary | Request name | | parameters (path/query/header) | URL path variables, query params, headers | | requestBody.content.application/json.schema | Body (raw JSON), generate example from schema | | responses | Saved example responses | | components.securitySchemes | Collection-level auth | | tags | Folder grouping |

Swagger 2 → Postman

| Swagger field | Postman mapping | |---|---| | host + basePath | {{base_url}} | | paths.<path>.<method> | Request item | | parameters | Query/path/header/body params | | consumes / produces | Content-Type / Accept headers | | securityDefinitions | Collection auth | | tags | Folders |

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:

| OpenAPI scheme | Postman auth type | |---|---| | http: bearer | bearer with {{token}} | | http: basic | basic with {{username}} / {{password}} | | apiKey: header | apikey header with {{api_key}} | | apiKey: query | apikey query param | | oauth2 | oauth2 (note: requires manual token setup) |

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
• [ ] Auth tokens are {{variables}}, never hardcoded
• [ ] JSON output is valid and importable

After Completing the API Design

Once the API design output is delivered, ask the user:

"Would you like me to generate API documentation for this design? (yes/no)"

If the user says yes:

• Check if the API Documentation skill is available in the installed skills list
• If the skill is available:
• Read and follow the instructions in the API Documentation skill
• Use the API design output above as the input
• If the skill is NOT available:
• Inform the user: "It looks like the API Documentation skill isn't installed. You can install it and re-run.

If the user says no:

• End the task here