swapper

A CLI tool for generating TypeScript API functions and type definitions from Swagger/OpenAPI documents.

By default, the generated output is written into two files inside the target directory:

• types.ts: type definitions
• index.ts: API request functions

Requirements

• Node.js >= 18

Installation

For local development:

pnpm install

pnpm link

Install it globally with:

npm install -g @aircan/swapper

Then run the CLI with:

swapper --help

You can also run the published package directly with:

npx @aircan/swapper --help

Install the built-in skill for Codex or Claude Code:

swapper install-skill

The command opens an interactive selector so you can choose Codex or Claude Code with arrow keys.

When the skill is used by an agent, the expected execution path is to try the globally installed swapper command first. If availability is unclear, verify with swapper --help before falling back to a repo-local entrypoint.

Usage

swapper -u <swagger-url> -t <tags> -d <output-dir> -r <request-import> [options]

An explicit subcommand form is also supported:

swapper generate -u <swagger-url> -t <tags> -d <output-dir> -r <request-import> [options]

Basic Examples

Generate by controller:

swapper \
  -u https://swagger-page.com/promotion/api/v2/api-docs \
  --tag activity \
  --dir ./api \
  --prefix /promotion/api \
  -r "import request from '@/utils/request';"

Generate specific endpoints:

swapper \
  -u https://swagger-page.com/promotion/api/v2/api-docs \
  --tag GET-/calcProcessConfig,POST-/calcProcessConfig \
  --dir ./api \
  --prefix /promotion/api \
  -r "import request from '@/utils/request';"

Generate a mixed selection:

swapper \
  -u https://petstore.swagger.io/v2/swagger.json \
  --tag DyLkProductMapping,POST-/dyLkProductMapping \
  --dir ./src/services \
  -r "import { request } from 'umi';"

Options

Option	Short	Required	Default	Description
--url	-u	Yes	None	Swagger document URL
--tag	-t	Yes	None	Interfaces to generate. Supports controller names or METHOD-/path, separated by commas
--dir	-d	Yes	None	Output directory
--request	-r	Yes	None	Import statement for the request function
--out-type		No	ts	Output file type. Currently supports ts and js
--prefix	-p	No	None	Prefix appended to generated request URLs
--force		No	false	Fully overwrite output files instead of incremental merge

Install the Skill

Install the bundled generate-swagger-types skill into Codex or Claude Code on the current machine:

swapper install-skill

The command opens an interactive selector for Codex or Claude Code. If you choose Codex, it installs to:

${CODEX_HOME:-~/.codex}/skills/generate-swagger-types

If you choose Claude Code, it installs to:

${CLAUDE_CONFIG_DIR:-~/.claude}/skills/generate-swagger-types

To skip the prompt, pass --agent:

swapper install-skill --agent claude-code

Optional flags:

Option	Required	Default	Description
--agent	No	Interactive selector in TTY; codex in non-interactive shells	Target agent. Supports codex, claude-code, and claude
--dest	No	Depends on --agent	Custom skill installation root
--force	No	true	Overwrite the destination if the skill already exists
--no-force	No	false	Fail when the destination skill already exists

Examples:

swapper install-skill --dest ~/.codex/skills
swapper install-skill --agent claude-code
swapper install-skill --no-force

Restart Codex or Claude Code after installation so the new skill can be loaded.

Generation Behavior

Incremental merge is the default mode:

• Existing types.ts and index.ts files are read first
• Newly generated types are merged into types.ts
• Newly generated functions are merged into index.ts
• Existing types and functions with the same name are replaced by the latest generated versions

When --force is used:

• types.ts and index.ts in the target directory are overwritten directly

Output Example

Running:

swapper \
  -u https://swagger-page.com/promotion/api/v2/api-docs \
  --tag activity \
  --dir ./api \
  --prefix /promotion/api \
  -r "import request from '@/utils/request';"

will generate:

api/
├── index.ts
└── types.ts

Where:

• types.ts contains response, request body, and query parameter type definitions
• index.ts contains request functions and import type statements

Development

Show help:

node bin/swapper.js --help

Run directly:

node bin/swapper.js \
  -u https://swagger-page.com/promotion/api/v2/api-docs \
  --tag activity \
  --dir ./api \
  --prefix /promotion/api \
  -r "import request from '@/utils/request';"