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;
function generateInsomniaCollection(
routes: RouteInfo[],
options: {
name: string;
baseUrl: string;
description?: string;
}
): InsomniaExport {
const workspaceId = `wrk_${uuidv4().replace(/-/g, "")}`;
const baseEnvId = `env_${uuidv4().replace(/-/g, "")}`;
const devEnvId = `env_${uuidv4().replace(/-/g, "")}`;
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