Postman Collection Generator

Generate importable Postman collections from your API codebase automatically.

Core Workflow

• Scan routes: Find all API route definitions in the codebase

• Extract metadata: Methods, paths, params, request bodies, headers

• Organize endpoints: Group by resource or folder structure

• Generate collection: Create Postman Collection v2.1 JSON

• Add examples: Include request/response examples

• Configure variables: Environment variables for base URL, auth tokens

Supported Frameworks

Framework Route Pattern Detection

Express app.get() , router.post()

Method chaining on app/router

Next.js app/api/**/route.ts

File-based routing

Fastify fastify.get() , route schema Method + schema decorators

Hono app.get() , app.post()

Similar to Express

NestJS @Get() , @Post() decorators Decorator-based

Koa router.get() , router.post()

Koa-router patterns

Postman Collection v2.1 Schema

{ "info": { "name": "API Collection", "description": "Auto-generated from codebase", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [], "variable": [], "auth": {} }

Express Route Scanner

// scripts/generate-postman.ts import * as fs from "fs"; import * as path from "path"; import { parse } from "@babel/parser"; import traverse from "@babel/traverse";

interface RouteInfo { method: string; path: string; name: string; description?: string; params?: ParamInfo[]; body?: Record<string, unknown>; headers?: Record<string, string>; }

interface ParamInfo { name: string; type: "path" | "query"; description?: string; example?: string; }

function scanExpressRoutes(filePath: string): RouteInfo[] { const routes: RouteInfo[] = []; const code = fs.readFileSync(filePath, "utf-8");

const ast = parse(code, { sourceType: "module", plugins: ["typescript"], });

traverse(ast, { CallExpression(nodePath) { const callee = nodePath.node.callee;

  if (callee.type === "MemberExpression") {
    const method = callee.property.name;
    const httpMethods = ["get", "post", "put", "patch", "delete"];

    if (httpMethods.includes(method)) {
      const args = nodePath.node.arguments;
      if (args[0]?.type === "StringLiteral") {
        const routePath = args[0].value;

        routes.push({
          method: method.toUpperCase(),
          path: routePath,
          name: generateRouteName(method, routePath),
          params: extractParams(routePath),
        });
      }
    }
  }
},

});

return routes; }

function extractParams(routePath: string): ParamInfo[] { const params: ParamInfo[] = []; const pathParamRegex = /:(\w+)/g; let match;

while ((match = pathParamRegex.exec(routePath)) !== null) { params.push({ name: match[1], type: "path", example: {{${match[1]}}}, }); }

return params; }

function generateRouteName(method: string, path: string): string { const cleanPath = path.replace(/[/:]/g, " ").trim(); return ${method.toUpperCase()} ${cleanPath}; }

Next.js App Router Scanner

// scripts/scan-nextjs-routes.ts import * as fs from "fs"; import * as path from "path"; import { glob } from "glob";

interface NextApiRoute { method: string; path: string; filePath: string; }

async function scanNextJsRoutes(appDir: string): Promise<NextApiRoute[]> { const routes: NextApiRoute[] = []; const routeFiles = await glob(${appDir}/**/route.{ts,js});

for (const file of routeFiles) { const content = fs.readFileSync(file, "utf-8"); const relativePath = path.relative(appDir, path.dirname(file)); const apiPath = "/" + relativePath.replace(/\/g, "/");

// Detect exported HTTP methods
const methods = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];

for (const method of methods) {
  if (
    content.includes(`export async function ${method}`) ||
    content.includes(`export function ${method}`) ||
    content.includes(`export const ${method}`)
  ) {
    routes.push({
      method,
      path: convertNextPathToPostman(apiPath),
      filePath: file,
    });
  }
}

}

return routes; }

function convertNextPathToPostman(nextPath: string): string { // Convert [param] to :param return nextPath .replace(/[...(\w+)]/g, ":$1*") // [...slug] -> :slug* .replace(/[(\w+)]/g, ":$1"); // [id] -> :id }

Fastify Route Scanner

// scripts/scan-fastify-routes.ts interface FastifyRoute { method: string; path: string; schema?: { body?: object; querystring?: object; params?: object; response?: object; }; }

function scanFastifyRoutes(filePath: string): FastifyRoute[] { const routes: FastifyRoute[] = []; const code = fs.readFileSync(filePath, "utf-8");

// Match fastify.get('/path', { schema: ... }, handler) const routeRegex = /fastify.(get|post|put|patch|delete)\s*(\s*['"]([^'"]+)['"`]\s*,\s*({[\s\S]?})\s,/g;

let match; while ((match = routeRegex.exec(code)) !== null) { const [, method, path, optionsStr] = match;

routes.push({
  method: method.toUpperCase(),
  path,
  // Parse schema from options if available
});

}

return routes; }

Collection Generator

// scripts/generate-collection.ts interface PostmanCollection { info: { name: string; description: string; schema: string; }; item: PostmanItem[]; variable: PostmanVariable[]; auth?: PostmanAuth; }

interface PostmanItem { name: string; request: { method: string; header: PostmanHeader[]; url: PostmanUrl; body?: PostmanBody; description?: string; }; response?: PostmanResponse[]; }

interface PostmanUrl { raw: string; host: string[]; path: string[]; query?: PostmanQuery[]; variable?: PostmanPathVariable[]; }

interface PostmanVariable { key: string; value: string; type: string; }

function generatePostmanCollection( routes: RouteInfo[], options: { name: string; baseUrl: string; description?: string; auth?: "bearer" | "basic" | "apikey"; } ): PostmanCollection { const collection: PostmanCollection = { info: { name: options.name, description: options.description || "Auto-generated API collection", schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", }, item: [], variable: [ { key: "baseUrl", value: options.baseUrl, type: "string" }, { key: "authToken", value: "", type: "string" }, ], };

// Add auth configuration if (options.auth === "bearer") { collection.auth = { type: "bearer", bearer: [{ key: "token", value: "{{authToken}}", type: "string" }], }; }

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

for (const [resource, resourceRoutes] of Object.entries(groupedRoutes)) { const folder: PostmanItem = { name: resource, item: resourceRoutes.map((route) => createPostmanRequest(route)), }; collection.item.push(folder); }

return collection; }

function createPostmanRequest(route: RouteInfo): PostmanItem { const pathSegments = route.path.split("/").filter(Boolean);

const item: PostmanItem = { name: route.name, request: { method: route.method, header: [ { key: "Content-Type", value: "application/json", type: "text" }, ], url: { raw: {{baseUrl}}${route.path}, host: ["{{baseUrl}}"], path: pathSegments, variable: route.params ?.filter((p) => p.type === "path") .map((p) => ({ key: p.name, value: p.example || "", description: p.description, })), }, description: route.description, }, };

// Add request body for POST/PUT/PATCH if (["POST", "PUT", "PATCH"].includes(route.method) && route.body) { item.request.body = { mode: "raw", raw: JSON.stringify(route.body, null, 2), options: { raw: { language: "json" } }, }; }

return item; }

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

for (const route of routes) { // Extract resource from path (e.g., /api/users/:id -> users) const parts = route.path.split("/").filter(Boolean); const resource = parts[1] || parts[0] || "root";

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

}

return groups; }

CLI Script

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

program .name("postman-gen") .description("Generate Postman collection from API routes") .option("-f, --framework <type>", "Framework type", "express") .option("-s, --source <path>", "Source directory", "./src") .option("-o, --output <path>", "Output file", "./postman-collection.json") .option("-n, --name <name>", "Collection name", "API Collection") .option("-b, --base-url <url>", "Base URL", "http://localhost:3000") .option("-a, --auth <type>", "Auth type (bearer|basic|apikey)") .parse();

const options = program.opts();

async function main() { let routes: RouteInfo[] = [];

switch (options.framework) { case "express": routes = await scanExpressProject(options.source); break; case "nextjs": routes = await scanNextJsRoutes(path.join(options.source, "app/api")); break; case "fastify": routes = await scanFastifyProject(options.source); break; default: console.error(Unsupported framework: ${options.framework}); process.exit(1); }

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

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

main();

Environment Template

{ "name": "Development", "values": [ { "key": "baseUrl", "value": "http://localhost:3000/api", "enabled": true }, { "key": "authToken", "value": "", "enabled": true, "type": "secret" }, { "key": "userId", "value": "1", "enabled": true } ] }

Example Output

{ "info": { "name": "My API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "Users", "item": [ { "name": "GET users", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/users", "host": ["{{baseUrl}}"], "path": ["users"], "query": [ { "key": "page", "value": "1" }, { "key": "limit", "value": "10" } ] } } }, { "name": "GET user by ID", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/users/:id", "host": ["{{baseUrl}}"], "path": ["users", ":id"], "variable": [{ "key": "id", "value": "{{userId}}" }] } } }, { "name": "POST create user", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "body": { "mode": "raw", "raw": "{\n "name": "John Doe",\n "email": "john@example.com"\n}" }, "url": { "raw": "{{baseUrl}}/users", "host": ["{{baseUrl}}"], "path": ["users"] } } } ] } ], "variable": [ { "key": "baseUrl", "value": "http://localhost:3000/api" }, { "key": "authToken", "value": "" } ] }

Best Practices

• Use variables: {{baseUrl}} , {{authToken}} for flexibility

• Group endpoints: Organize by resource/feature folders

• Add descriptions: Document each endpoint's purpose

• Include examples: Pre-fill request bodies with realistic data

• Set up auth: Configure collection-level authentication

• Add tests: Include basic response validation scripts

• Version control: Commit collection JSON to repository

• CI integration: Auto-generate on route changes

Output Checklist

• All routes scanned from codebase

• Endpoints grouped by resource

• Path parameters extracted

• Request bodies included for POST/PUT/PATCH

• Environment variables configured

• Authentication setup (if applicable)

• Collection exported as v2.1 JSON

• Environment template created