Agent-skills postman-openapi-converter

install

source · Clone the upstream repo

git clone https://github.com/LambdaTest/agent-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/LambdaTest/agent-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/api/Postman/postman-openapi-converter" ~/.claude/skills/lambdatest-agent-skills-postman-openapi-converter && rm -rf "$T"

manifest: api/Postman/postman-openapi-converter/SKILL.md

source content

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

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

```
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