08 - Import: OpenAPI, Swagger, and Postman

Supported Source Types

Import source can be:

• Local file (json, yaml, yml)
• Remote URL

Supported specification families:

• OpenAPI 3.x
• Swagger 2.0
• Postman collections

Parsing Strategy

Importer tries:

1. JSON parse
2. YAML parse fallback

If neither yields an object, import fails with validation error.

OpenAPI and Swagger Import

Base URL Derivation

• OpenAPI 3.x: first server URL (variables replaced with defaults)
• Swagger 2.0: scheme + host + basePath

Generated requests use URL template:

• {{baseUrl}}<path>

Importer also creates folder variable entry:

• key: baseUrl
• value: computed base URL

Operation Extraction

For each path + HTTP method:

• merges path-level and operation-level parameters
• builds query params and header params
• infers body from requestBody (OpenAPI) or body/formData params (Swagger)

Foldering Strategy

Requests are grouped under:

• Collection folder from spec title
• Child folder from first operation tag (or first non-variable path segment fallback)

Postman Import

Collection Recognition

Detected by Postman schema marker in info.schema or collection-like shape.

Item Walk

Importer recursively walks item folders and request items:

• Nested Postman folders become nested directories
• Request names become request file names

URL and Params

URL built from Postman raw URL or structured URL object. Query parameters are extracted and normalized.

Body Modes

Handled modes include:

• raw
• urlencoded
• graphql
• formdata (with fallback notes for file-based multipart cases)

Script Extraction

Postman event scripts are mapped to request draft fields:

• prerequest -> preRequestScript
• test -> testScript

Preview Statuses

Each candidate in preview is tagged as:

• new: no matching source and no path collision
• match: same import identity/operation identity already exists
• conflict: desired path collides with different existing item

Import Modes

1. create-new

• Always create new request entries

2. replace-existing

• Replace matching imports when source identity matches

3. skip-existing

• Skip when matching import or direct path conflict is detected

Matching Logic

OpenAPI match checks:

• sourceIdentity
• operationKey

Postman match checks:

• sourceIdentity
• itemKey

Known Limitations

• External $ref references are not supported.
• Some advanced auth and multipart edge cases may need manual post-import edits.
• Imported examples are best-effort and should be reviewed before production use.