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

---