insomnia-collection-generator

Insomnia Collection Generator

Generate importable Insomnia workspaces from your API codebase automatically.

Core Workflow

Scan routes: Find all API route definitions
Extract metadata: Methods, paths, params, bodies
Create workspace: Organize into request groups
Configure environments: Base URLs, auth tokens
Add authentication: Bearer, Basic, API Key
Export collection: Insomnia v4 JSON format

Insomnia Export v4 Schema

{ "_type": "export", "__export_format": 4, "__export_date": "2024-01-15T10:30:00.000Z", "__export_source": "insomnia.desktop.app:v2023.5.8", "resources": [] }

Resource Types

interface InsomniaWorkspace { _id: string; _type: "workspace"; name: string; description: string; scope: "collection" | "design"; }

interface InsomniaRequestGroup { _id: string; _type: "request_group"; name: string; parentId: string; description?: string; }

interface InsomniaRequest { _id: string; _type: "request"; name: string; parentId: string; method: string; url: string; body: InsomniaBody; headers: InsomniaHeader[]; parameters: InsomniaParameter[]; authentication: InsomniaAuth; }

interface InsomniaEnvironment { _id: string; _type: "environment"; name: string; parentId: string; data: Record<string, string>; }

Collection Generator

// scripts/generate-insomnia.ts import { v4 as uuidv4 } from "uuid";

interface RouteInfo { method: string; path: string; name: string; body?: object; params?: { name: string; type: "path" | "query" }[]; }

interface InsomniaExport { _type: "export"; __export_format: 4; __export_date: string; __export_source: string; resources: InsomniaResource[]; }

type InsomniaResource = | InsomniaWorkspace | InsomniaRequestGroup | InsomniaRequest | InsomniaEnvironment;

const resources: InsomniaResource[] = [];

// Create workspace resources.push({ _id: workspaceId, _type: "workspace", name: options.name, description: options.description || "Auto-generated API collection", scope: "collection", });

// Create base environment resources.push({ _id: baseEnvId, _type: "environment", name: "Base Environment", parentId: workspaceId, data: {}, });

// Create development environment resources.push({ _id: devEnvId, _type: "environment", name: "Development", parentId: baseEnvId, data: { base_url: options.baseUrl, auth_token: "", }, });

// Group routes by resource const groupedRoutes = groupRoutesByResource(routes);

for (const [resource, resourceRoutes] of Object.entries(groupedRoutes)) { // Create request group (folder) const groupId = fld_${uuidv4().replace(/-/g, "")};

resources.push({
  _id: groupId,
  _type: "request_group",
  name: capitalize(resource),
  parentId: workspaceId,
  description: `${resource} endpoints`,
});

// Create requests in group
for (const route of resourceRoutes) {
  resources.push(createInsomniaRequest(route, groupId));
}

}

return { _type: "export", __export_format: 4, __export_date: new Date().toISOString(), __export_source: "api-generator:v1.0.0", resources, }; }

function createInsomniaRequest( route: RouteInfo, parentId: string ): InsomniaRequest { const requestId = req_${uuidv4().replace(/-/g, "")};

// Convert :param to {{ _.param }} for Insomnia const url = route.path.replace(/:(\w+)/g, "{{ _.$1 }}");

const request: InsomniaRequest = { _id: requestId, _type: "request", name: route.name, parentId, method: route.method, url: {{ _.base_url }}${url}, body: { mimeType: "application/json", text: route.body ? JSON.stringify(route.body, null, 2) : "", }, headers: [ { name: "Content-Type", value: "application/json", }, ], parameters: route.params ?.filter((p) => p.type === "query") .map((p) => ({ name: p.name, value: "", disabled: false, })) || [], authentication: { type: "bearer", token: "{{ _.auth_token }}", disabled: true, }, };

return request; }

function groupRoutesByResource( routes: RouteInfo[] ): Record<string, RouteInfo[]> { const groups: Record<string, RouteInfo[]> = {};

for (const route of routes) { const parts = route.path.split("/").filter(Boolean); const resource = parts[0] || "root";

if (!groups[resource]) {
  groups[resource] = [];
}
groups[resource].push(route);

}

return groups; }

function capitalize(str: string): string { return str.charAt(0).toUpperCase() + str.slice(1); }

Complete Export Example

{ "_type": "export", "__export_format": 4, "__export_date": "2024-01-15T10:30:00.000Z", "__export_source": "api-generator:v1.0.0", "resources": [ { "_id": "wrk_abc123", "_type": "workspace", "name": "My API", "description": "Auto-generated API collection", "scope": "collection" }, { "_id": "env_base123", "_type": "environment", "name": "Base Environment", "parentId": "wrk_abc123", "data": {} }, { "_id": "env_dev123", "_type": "environment", "name": "Development", "parentId": "env_base123", "data": { "base_url": "http://localhost:3000/api", "auth_token": "" } }, { "_id": "env_prod123", "_type": "environment", "name": "Production", "parentId": "env_base123", "data": { "base_url": "https://api.example.com", "auth_token": "" } }, { "_id": "fld_users123", "_type": "request_group", "name": "Users", "parentId": "wrk_abc123" }, { "_id": "req_getusers", "_type": "request", "name": "Get All Users", "parentId": "fld_users123", "method": "GET", "url": "{{ _.base_url }}/users", "body": {}, "headers": [ { "name": "Content-Type", "value": "application/json" } ], "parameters": [ { "name": "page", "value": "1", "disabled": false }, { "name": "limit", "value": "10", "disabled": false } ], "authentication": { "type": "bearer", "token": "{{ _.auth_token }}" } }, { "_id": "req_getuser", "_type": "request", "name": "Get User by ID", "parentId": "fld_users123", "method": "GET", "url": "{{ _.base_url }}/users/{{ _.user_id }}", "body": {}, "headers": [], "authentication": {} }, { "_id": "req_createuser", "_type": "request", "name": "Create User", "parentId": "fld_users123", "method": "POST", "url": "{{ _.base_url }}/users", "body": { "mimeType": "application/json", "text": "{\n "name": "John Doe",\n "email": "john@example.com"\n}" }, "headers": [ { "name": "Content-Type", "value": "application/json" } ], "authentication": { "type": "bearer", "token": "{{ _.auth_token }}" } } ] }

Authentication Types

// Bearer Token { "type": "bearer", "token": "{{ _.auth_token }}", "prefix": "Bearer" }

// Basic Auth { "type": "basic", "username": "{{ _.username }}", "password": "{{ _.password }}" }

// API Key { "type": "apikey", "key": "X-API-Key", "value": "{{ _.api_key }}", "addTo": "header" }

// OAuth 2.0 { "type": "oauth2", "grantType": "authorization_code", "authorizationUrl": "https://auth.example.com/authorize", "accessTokenUrl": "https://auth.example.com/token", "clientId": "{{ _.client_id }}", "clientSecret": "{{ _.client_secret }}", "scope": "read write" }

Request Body Types

// JSON Body { "mimeType": "application/json", "text": "{"name": "value"}" }

// Form URL Encoded { "mimeType": "application/x-www-form-urlencoded", "params": [ { "name": "field1", "value": "value1" }, { "name": "field2", "value": "value2" } ] }

// Multipart Form (file upload) { "mimeType": "multipart/form-data", "params": [ { "name": "file", "type": "file", "fileName": "" }, { "name": "description", "value": "File description" } ] }

// GraphQL { "mimeType": "application/graphql", "text": "query { users { id name } }" }

CLI Script

#!/usr/bin/env node // scripts/insomnia-gen.ts import * as fs from "fs"; import { program } from "commander";

program .name("insomnia-gen") .description("Generate Insomnia collection from API routes") .option("-f, --framework <type>", "Framework type", "express") .option("-s, --source <path>", "Source directory", "./src") .option("-o, --output <path>", "Output file", "./insomnia-collection.json") .option("-n, --name <name>", "Workspace name", "API Collection") .option("-b, --base-url <url>", "Base URL", "http://localhost:3000/api") .parse();

const options = program.opts();

async function main() { const routes = await scanRoutes(options.framework, options.source);

const collection = generateInsomniaCollection(routes, { name: options.name, baseUrl: options.baseUrl, });

fs.writeFileSync(options.output, JSON.stringify(collection, null, 2)); console.log(Generated ${options.output} with ${routes.length} requests); }

main();

Environment Templates

{ "_id": "env_development", "_type": "environment", "name": "Development", "data": { "base_url": "http://localhost:3000/api", "auth_token": "", "user_id": "1" } }

{ "_id": "env_staging", "_type": "environment", "name": "Staging", "data": { "base_url": "https://staging-api.example.com", "auth_token": "", "user_id": "test-user-123" } }

{ "_id": "env_production", "_type": "environment", "name": "Production", "data": { "base_url": "https://api.example.com", "auth_token": "", "user_id": "" } }

Best Practices

Use environments: Store base URLs and tokens as variables
Organize folders: Group requests by resource/feature
Template syntax: Use {{ _.variable }} for dynamic values
Authentication: Configure at workspace level when possible
Add descriptions: Document each request's purpose
Include examples: Pre-fill request bodies with realistic data
Version control: Commit export JSON to repository
Multiple envs: Create dev, staging, production environments

Output Checklist

All routes scanned from codebase
Workspace created with proper scope
Request groups organized by resource
Requests include proper methods and URLs
Path parameters converted to {{ _.param }} syntax
Request bodies included for POST/PUT/PATCH
Headers configured (Content-Type, etc.)
Environments created (dev, staging, prod)
Authentication configured
Export validates in Insomnia

insomnia-collection-generator

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

framer-motion-animator

eslint-prettier-config

postman-collection-generator

changelog-writer