🛠️ Openapi2Insomnia

Converts an OpenAPI 3.0.x specification into an Insomnia v5 collection ready to import and run tests.

Generates one test case (TC) per operation response code — base success TC, per-parameter variants, and error TCs (400, 401, 403, 404) — each with an afterResponse validation script that checks the status code and validates the response body against the schema.

Requirements

• Node.js >= 20
• pnpm >= 9 (development only)

Installation

npm install -g openapi2insomnia

Development setup

git clone https://github.com/apiaddicts/openapi2insomnia
cd openapi2insomnia
pnpm install
pnpm build

Usage

Installed from npm

o2i convert -i <path|url> [options]

Local development

node dist/index.js convert -i <path|url> [options]

Flags

| Flag | Required | Description | |------|----------|-------------| | -i, --input <path\|url> | yes | Path to a local file or an HTTPS URL | | -o, --output <path> | no | Output file path. If omitted, writes to stdout | | -c, --config <path> | no | Path to an o2i.config.json file |

Examples

# Output to stdout
o2i convert -i openapi.yaml

# Output to a file
o2i convert -i openapi.yaml -o collection.yaml

# With config (generates one file per environment)
o2i convert -i openapi.yaml -c o2i.config.json

# From a remote URL
o2i convert -i https://api.example.com/openapi.yaml -o collection.yaml

Config file

Without a config file the tool generates a single collection using the spec's server URL as base_url.

With a config file you can generate one collection per environment, each with its own URL, OAuth2 credentials, and generation options.

{
  "minimal_endpoints": false,
  "generate_oneOf_anyOf": false,
  "examples": {
    "correct": {
      "string": "goodstring",
      "integer": 1,
      "number": 1.0,
      "boolean": true,
      "date": "2020-01-01",
      "date-time": "2020-01-01T23:59:59"
    },
    "wrong": {
      "string": "badstring",
      "integer": "badstring",
      "number": "badstring",
      "boolean": "badboolean",
      "date": "2020-40-40",
      "date-time": "2020-40-40T00:00:00"
    }
  },
  "environments": [
    {
      "name": "DEV",
      "base_url": "https://dev.api.example.com/v1",
      "host_server_pattern": "%dev%",
      "token_url": "https://dev.keycloak.example.com/token",
      "authorization_url": "https://dev.keycloak.example.com/auth",
      "client_id": "my-client-dev",
      "client_secret": "",
      "target_folder": "out",
      "microcks_headers": true,
      "read_only": false,
      "has_scopes": true,
      "application_token": true,
      "number_of_scopes": 2
    }
  ]
}

Global options

| Field | Type | Default | Description | |-------|------|---------|-------------| | minimal_endpoints | boolean | false | Generate only the base success TC per operation, skipping optional-parameter and wrong-body variants. Error TCs (401, 403, 404) and one 400 are still generated. | | generate_oneOf_anyOf | boolean | false | When a request body uses oneOf/anyOf, generate a TC set per schema variant instead of using only the first. | | examples.correct | object | — | Values used as valid inputs in success TCs and environment variables. | | examples.wrong | object | — | Values used in 400 TCs to intentionally violate schema constraints. |

Environment options

| Field | Type | Default | Description | |-------|------|---------|-------------| | name | string | — | Environment name in Insomnia and output filename suffix. | | base_url | string | '' | Base URL of the API. Overridden if host_server_pattern finds a match. | | host_server_pattern | string | — | SQL-LIKE pattern (% = wildcard) matched against the spec's servers[] list to pick the right URL automatically. Case-insensitive. | | token_url | string | from spec | OAuth2 token endpoint. Overrides the value from the spec. | | authorization_url | string | from spec | OAuth2 authorization endpoint. | | client_id | string | '' | OAuth2 client ID. | | client_secret | string | '' | OAuth2 client secret. | | target_folder | string | '.' | Directory where the output YAML is written. Created if it does not exist. | | microcks_headers | boolean | false | Add X-Microcks-Response-Name header to every request, using the example name defined in the spec response. | | read_only | boolean | false | Generate TCs only for GET operations. | | has_scopes | boolean | false | Duplicate each 2xx TC for every configured token type (user scopes, application token). | | application_token | boolean | false | Include an application_token variant in scope clones. Requires has_scopes: true. | | number_of_scopes | integer | 0 | Number of user token scopes to generate (user_token_scope_1 … user_token_scope_N). |

Development

pnpm build        # compile TypeScript → dist/
pnpm dev          # compile in watch mode
pnpm test         # run unit tests
pnpm typecheck    # type-check without emitting

License

GNU Lesser General Public License v3.0