---
name: openapi-to-postman
description: >
  Convert an OpenAPI specification (YAML/JSON) to a Postman collection.
  Use when the user says /openapi-to-postman, 'convert openapi to postman',
  'postman collection from openapi', 'openapi vers postman', 'genere une collection postman',
  'export postman', or needs to create a Postman collection from an API spec.
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
  - AskUserQuestion
---

Convert an OpenAPI/Swagger specification to a Postman Collection v2.0.

Automatically replaces the base URL and recurring path parameters with Postman environment variables, configures collection-level authentication from the spec's security schemes, and generates companion environment files.

## Required tools

- `aws`
- `postman-mcp` (only with `--import-postman`)

Run `pysae-ai-tools tools require <tools>` before starting; if it exits non-zero, abort and report the install command from stderr to the user.

## Step 1 — Locate the OpenAPI spec

If the user doesn't provide a spec path, check two sources:

1. **Pysae API specs** — read `references/pysae-projects.md#openapi-specifications` for available spec URLs. Prefer `internal` visibility (includes all endpoints). Ask the user which version and environment they want.
2. **Local files** — search the current project:

```bash
find . -maxdepth 3 \( -name "openapi*.yaml" -o -name "openapi*.yml" -o -name "openapi*.json" -o -name "swagger*.yaml" -o -name "swagger*.yml" -o -name "swagger*.json" \) 2>/dev/null | head -10
```

## Step 2 — Convert and import

If `--import-postman` is requested, load the Postman API key first via the resolver (env → MCP config → AWS Secrets Manager) :

```bash
eval "$(pysae-ai-tools env resolve --set POSTMAN_API_KEY)" || exit 1
```

The script handles conversion, auth setup, multi-environment generation, and import to Postman in one command.

```bash
pysae-ai-tools openapi to-postman <SPEC_PATH> \
  --output <OUTPUT_PATH> \
  --env-name <PRIMARY_ENV_NAME> \
  --env-prefix <PREFIX> \
  --env-default VAR=VALUE \
  --extra-base-url "Name=URL" \
  --import-postman
```

**Arguments:**
- `<SPEC_PATH>` — Local file or URL
- `--output <path>` — Output file (default: `<spec-name>.postman_collection.json`)
- `--env-name <name>` — Primary environment name (default: derived from spec title)
- `--env-prefix <prefix>` — Prefix for all environment variable names (e.g. `PYSAE` → `PYSAE_BASE_URL`, `PYSAE_GROUP_ID`)
- `--env-default VAR=VALUE` — Set default values for environment variables (can be repeated)
- `--extra-base-url "Name=URL"` — Generate additional environments with different base URLs (can be repeated)
- `--extra-env <path>` — Additional manually-created environment files to import (can be repeated)
- `--min-occurrences <n>` — Minimum occurrences for a path param to become an env var (default: 2)
- `--import-postman` — Import collection + environments into Postman via the API (upsert)
- `--append-env` — Append-only environment upsert: add new variables but never remove existing ones
- `--workspace <id>` — Postman workspace ID (default: first personal workspace)
- `--login-endpoint <path>` — Add auto-login pre-request script (e.g. `/api/v4/login`). Calls this endpoint with email/password when the bearer token is expired.
- `--login-token-field <field>` — JSON field in login response containing the token (default: `session_id`)

The script:
1. Installs `openapi-to-postmanv2` CLI if missing
2. Downloads the spec if it's a URL
3. Converts with sensible defaults (Paths folders, schema faker, Fallback naming)
4. Extracts the base URL from the spec `servers` field → `{{PREFIX_BASE_URL}}`
5. Detects security schemes (bearer, apiKey, basic, openIdConnect) → sets collection-level auth with env var (e.g. `{{PYSAE_AUTH_BEARER_TOKEN}}`)
6. Detects path parameters used in >= 2 endpoints → `{{PREFIX_PARAM_NAME}}`
7. Generates `.postman_environment.json` files (one per environment) with all variables pre-configured
8. If `--import-postman`: **upserts** collection + environments via the Postman API

**Upsert behavior:**
- **Collections**: matched by name — updates if exists, creates if not
- **Environments**: matched by name — updates structure (adds new variables, removes obsolete ones) while **preserving non-empty values** set by the user

**API key resolution** — handled by `pysae-ai-tools env resolve` (see Step 2 preamble) : env → MCP config (`~/.claude.json`) → AWS Secrets Manager.

### Example: Pysae API — one collection per version, 4 environments

Import each API version (v3, v4, v5) as a separate collection. **Use the dev spec** (`api.dev.pysae.com`) as source — it may contain new endpoints not yet deployed to prod. Environments are shared (created on first run, upserted on subsequent runs).

Common flags for all versions:

```
COMMON="--env-prefix PYSAE \
  --env-default PYSAE_GROUP_ID=pysae \
  --extra-base-url 'Pysae Prod=https://api.pysae.com' \
  --extra-base-url 'Pysae Review=https://api.review.pysae.com' \
  --extra-base-url 'Pysae Local=http://127.0.0.1:8000' \
  --login-endpoint /api/v4/login \
  --import-postman"
```

Run one command per version. The **first version with the most endpoints** (usually v4) runs first with a full environment upsert; others use `--append-env`:

```bash
# v4 — largest version, full environment upsert + login script
pysae-ai-tools openapi to-postman \
  "https://api.dev.pysae.com/api/docs/v4/internal/openapi.json" \
  --env-name "Pysae Dev" $COMMON

# v3 — append-only (don't remove v4 variables from environments)
pysae-ai-tools openapi to-postman \
  "https://api.dev.pysae.com/api/docs/v3/internal/openapi.json" \
  --env-name "Pysae Dev" $COMMON --append-env

# v5 — append-only
pysae-ai-tools openapi to-postman \
  "https://api.dev.pysae.com/api/docs/v5/internal/openapi.json" \
  --env-name "Pysae Dev" $COMMON --append-env
```

Each version creates its own collection (e.g. "Pysae Internal API v4"), while the 4 environments are shared. The first run does a full upsert; subsequent runs use `--append-env` to only add new variables without removing existing ones.

The `--login-endpoint /api/v4/login` adds a pre-request script to each collection that auto-logs in when `PYSAE_AUTH_BEARER_TOKEN` is missing or expired, using `PYSAE_AUTH_EMAIL` / `PYSAE_AUTH_PASSWORD`. The login endpoint path is always `/api/v4/login` regardless of the collection version (it uses `BASE_URL` from the environment).

The spec is fetched from dev — switch to "Pysae Prod" environment in Postman to target production.

If `env resolve` fails (Postman API key unavailable), the user can import manually : **Postman > Import > Upload Files > select the `.postman_collection.json`**.

## Step 3 — Report

Tell the user:
- Output file path (collection + environments)
- Number of folders and requests generated
- Auth scheme detected and variable name
- List of environment variables created (with their default values if any)
- Whether the import to Postman succeeded (created vs updated)
- Remind to fill in the environment variable values before testing requests
