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 → "[email protected]", "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

collection.json — Full Postman Collection v2.1
environment.json — Matching environment file
Conversion summary: number of endpoints converted, folders created, auth type detected, any fields skipped or approximated
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

Postman Openapi Converter