express-postman-generator

Automatically generate Postman Collection v2.1 JSON files from Express.js applications.

Features

• ✨ Automatically extracts all routes from Express applications
• 🔄 Supports nested routers and route groups
• 📁 Optional grouping of routes by path prefix
• 🔐 Detects authentication middleware
• 📝 Generates valid Postman Collection v2.1 JSON
• 🎯 Handles route parameters (:id, :userId, etc.)
• 📋 Includes common headers (Content-Type, Accept)
• 🖥️ CLI support for easy integration
• 📘 TypeScript type definitions included

Installation

npm install express-postman-generator

Quick Start

Programmatic Usage

const express = require('express');
const { generatePostmanCollection } = require('express-postman-generator');

const app = express();

// Define your routes
app.get('/users', (req, res) => {
  res.json({ users: [] });
});

app.post('/users', (req, res) => {
  res.status(201).json({ message: 'User created' });
});

app.get('/users/:id', (req, res) => {
  res.json({ user: { id: req.params.id } });
});

// Generate Postman collection
generatePostmanCollection(app, {
  name: 'My API',
  output: './my-api-collection.json'
});

CLI Usage

# Basic usage
npx express-postman-generator --entry ./app.js

# With options
npx express-postman-generator --entry ./app.js --output ./api.json --name "My API"

# Group routes by prefix
npx express-postman-generator --entry ./app.js --group

API Reference

generatePostmanCollection(app, options)

Generates a Postman Collection v2.1 from an Express application.

Parameters

• app (Express.Application) - Your Express application instance
• options (Object) - Configuration options

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | name | string | "API Collection" | Name of the Postman collection | | baseUrl | string | "{{baseUrl}}" | Base URL variable for requests | | output | string | "./postman_collection.json" | Output file path | | includeHeaders | boolean | true | Include common headers in requests | | groupByPrefix | boolean | false | Group routes by path prefix into folders |

Returns

Returns the Postman collection object and saves it to the specified output file.

extractRoutes(app)

Extracts all routes from an Express application without generating a collection.

Parameters

• app (Express.Application) - Your Express application instance

Returns

Returns an array of route objects:

[
  {
    method: 'GET',
    path: '/users/:id',
    keys: [...],
    middlewares: ['auth']
  },
  // ...
]

Examples

Basic Example

const express = require('express');
const { generatePostmanCollection } = require('express-postman-generator');

const app = express();

app.get('/api/users', (req, res) => {});
app.post('/api/users', (req, res) => {});
app.get('/api/users/:id', (req, res) => {});

generatePostmanCollection(app, {
  name: 'User API',
  output: './user-api.json'
});

With Nested Routers

const express = require('express');
const { generatePostmanCollection } = require('express-postman-generator');

const app = express();

// Create a router for products
const productRouter = express.Router();
productRouter.get('/', (req, res) => {});
productRouter.get('/:id', (req, res) => {});
productRouter.post('/', (req, res) => {});

app.use('/api/products', productRouter);

generatePostmanCollection(app, {
  name: 'Product API',
  output: './product-api.json'
});

With Authentication Middleware

const express = require('express');
const { generatePostmanCollection } = require('express-postman-generator');

const app = express();

// Authentication middleware
function auth(req, res, next) {
  // Your auth logic
  next();
}

// Protected routes
app.get('/api/profile', auth, (req, res) => {});
app.put('/api/profile', auth, (req, res) => {});

generatePostmanCollection(app, {
  name: 'Authenticated API',
  output: './auth-api.json'
});

// The generator will automatically add Authorization headers to routes with 'auth' middleware

Grouped by Prefix

const express = require('express');
const { generatePostmanCollection } = require('express-postman-generator');

const app = express();

app.get('/users', (req, res) => {});
app.get('/users/:id', (req, res) => {});
app.get('/products', (req, res) => {});
app.get('/products/:id', (req, res) => {});

generatePostmanCollection(app, {
  name: 'Grouped API',
  output: './grouped-api.json',
  groupByPrefix: true  // Groups routes into 'Users' and 'Products' folders
});

Custom Base URL

const express = require('express');
const { generatePostmanCollection } = require('express-postman-generator');

const app = express();

app.get('/api/data', (req, res) => {});

generatePostmanCollection(app, {
  name: 'Production API',
  baseUrl: 'https://api.production.com',
  output: './production-api.json'
});

CLI Documentation

Installation

# Global installation
npm install -g express-postman-generator

# Or use with npx (no installation needed)
npx express-postman-generator --help

CLI Options

Usage:
  npx express-postman-generator [options]
  express-postman-generator --entry ./app.js --output ./collection.json

Options:
  -e, --entry <file>      Path to Express app entry file (required)
  -o, --output <file>     Output path for collection JSON (default: ./postman_collection.json)
  -n, --name <name>       Collection name (default: "API Collection")
  -b, --baseUrl <url>     Base URL variable (default: "{{baseUrl}}")
  -g, --group             Group routes by path prefix
  --no-headers            Don't include default headers
  -h, --help              Show help message
  -v, --version           Show version number

CLI Examples

# Basic usage
npx express-postman-generator --entry ./app.js

# With custom name and output
npx express-postman-generator -e ./server.js -o ./my-api.json -n "My API"

# Group routes by prefix
npx express-postman-generator --entry ./app.js --group

# Custom base URL
npx express-postman-generator -e ./app.js -b "https://api.example.com"

# Without default headers
npx express-postman-generator -e ./app.js --no-headers

Important: Exporting Your App

For the CLI to work, your Express app file must export the app instance:

// app.js
const express = require('express');
const app = express();

// Your routes...
app.get('/api/users', (req, res) => {});

// Export the app
module.exports = app;

// Optional: Start server only when run directly
if (require.main === module) {
  app.listen(3000, () => {
    console.log('Server running on port 3000');
  });
}

Authentication Detection

The package automatically detects authentication middleware and adds appropriate headers. It looks for middleware with these names:

• auth
• authenticate
• authenticated
• isAuthenticated
• requireAuth

When detected, it adds an Authorization: Bearer {{token}} header to those routes.

Generated Collection Structure

The generated Postman collection includes:

• Collection metadata (name, description, schema version)
• Environment variable for base URL (default: {{baseUrl}})
• Requests with:
  • Proper HTTP methods
  • Path parameters as variables
  • Headers (Content-Type, Accept, Authorization if needed)
  • Request body templates for POST/PUT/PATCH
• Folders (if groupByPrefix: true)

TypeScript Support

This package includes TypeScript type definitions:

import express from 'express';
import { generatePostmanCollection, PostmanCollectionOptions } from 'express-postman-generator';

const app = express();

const options: PostmanCollectionOptions = {
  name: 'My API',
  output: './collection.json',
  groupByPrefix: true
};

generatePostmanCollection(app, options);

Testing

Run the included tests:

npm test

This will generate several example collections from the sample Express app in the example folder.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © Muhammad Zubair Shabbir

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Changelog

v1.0.0

• Initial release
• Support for Express 4.x and 5.x
• Automatic route extraction
• Nested router support
• CLI tool
• TypeScript definitions
• Authentication middleware detection
• Grouping by path prefix

Roadmap

• [ ] Support for request body examples from validation schemas
• [ ] Extract query parameters from route handlers
• [ ] Support for response examples
• [ ] Environment variable extraction
• [ ] Support for OpenAPI/Swagger annotations
• [ ] Custom header configuration
• [ ] Pre-request scripts generation

Related Projects

• Postman Collection SDK
• Express.js

Made with ❤️ for the Express.js community