Express Postman Generator

Generate Postman collections from your Express.js routes with a single command! 🚀

No more manual API documentation pain. This tool automatically analyzes your Express.js application, extracts all routes, and generates a ready-to-use Postman collection.

Features

• 🔍 Automatic Route Detection - Scans your Express.js project and finds all routes
• 📊 Smart Parsing - Uses AST parsing to understand route handlers, parameters, query strings, and body data
• 🎯 Controller Support - Follows function references to controller files and extracts parameters
• 📝 Complete Information - Extracts path params, query params, body params, and detects form-data vs JSON
• 📁 Organized Structure - Groups routes into folders by endpoint prefix
• ⚙️ Configurable - Customize via CLI options or config file
• 🎯 Zero Config - Works out of the box with sensible defaults

Installation

Global Installation (Recommended)

npm install -g @rashid5925/express-postman-generator

Local Installation

npm install --save-dev @rashid5925/express-postman-generator

Use with npx (No Installation)

npx @rashid5925/express-postman-generator

Quick Start

Navigate to your Express.js project directory and run:

express-postman

That's it! Your Postman collection will be generated and saved.

Usage

Basic Usage

# Generate collection in current directory
express-postman

# Specify project path
express-postman --project ./my-express-app

# Custom output path
express-postman --output ./docs/api-collection.json

# Custom collection name
express-postman --name "My Awesome API"

# Custom base URL
express-postman --base-url "https://api.myapp.com"

CLI Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --project <path> | -p | Path to Express.js project | Current directory | | --output <path> | -o | Output path for collection file | {collection-name}.postman_collection.json | | --name <name> | -n | Collection name | Express API Collection | | --base-url <url> | -b | Base URL for API | http://localhost:3000 | | --description <desc> | -d | Collection description | Generated from Express.js routes | | --config <path> | -c | Path to config file | .postmanrc.json | | --include <patterns...> | -i | File patterns to include | **/*.js | | --exclude <patterns...> | -e | File patterns to exclude | node_modules/**, test/** |

Configuration File

Create a .postmanrc.json file in your project root for persistent configuration:

{
  "collectionName": "My API Collection",
  "baseUrl": "http://localhost:3000",
  "description": "API endpoints for my Express.js application",
  "outputPath": "./postman-collection.json",
  "includePatterns": [
    "routes/**/*.js",
    "src/routes/**/*.js",
    "api/**/*.js"
  ],
  "excludePatterns": [
    "node_modules/**",
    "test/**",
    "tests/**",
    "**/*.test.js",
    "**/*.spec.js"
  ]
}

Then simply run:

express-postman

How It Works

The generator works in three steps:

1. 🔍 Route Discovery - Scans your project files for Express route definitions
2. 🔬 Smart Analysis - Uses Babel AST parser to analyze:
   • HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
   • Route paths and parameters
   • Controller functions - Follows require() to find handlers in separate files
   • Request body usage (req.body.*)
   • Query parameters (req.query.*)
   • Path parameters (:id, :userId, etc.)
   • File uploads (detects req.file / req.files for multipart form-data)
3. 📦 Collection Generation - Converts parsed routes to Postman Collection v2.1 format

Examples

Example Express.js Route File

// routes/users.js
const express = require('express');
const router = express.Router();

// GET /users
router.get('/', (req, res) => {
  const { page, limit } = req.query;
  // ... handler code
});

// GET /users/:id
router.get('/:id', (req, res) => {
  const { id } = req.params;
  // ... handler code
});

// POST /users
router.post('/', (req, res) => {
  const { name, email, age } = req.body;
  // ... handler code
});

module.exports = router;

Example with Controller Functions

// routes/orders.js
const express = require('express');
const router = express.Router();
const orderController = require('../controller/orderController');

router.get('/', orderController.getAllOrders);
router.post('/', orderController.createOrder);

module.exports = router;

// controller/orderController.js
const getAllOrders = (req, res) => {
  const { status, page, limit } = req.query;
  // Business logic here
  res.json({ orders: [] });
};

const createOrder = (req, res) => {
  const { customerId, items, shippingAddress } = req.body;
  // Create order logic
  res.status(201).json({ order: {} });
};

module.exports = { getAllOrders, createOrder };

The generator will:

• Follow the require() to find orderController.js
• Extract parameters from controller functions
• Generate proper Postman requests with all parameters!

Generated Postman Collection

The above routes will generate a Postman collection with:

• GET /users - with query parameters: page, limit
• GET /users/:id - with path parameter: id
• POST /users - with JSON body: name, email, age
• PUT /users/:id - with path parameter id and JSON body: name, email
• DELETE /users/:id - with path parameter: id

All organized in a "Users" folder with proper request configurations.

Supported Features

✅ Automatically Detected

• HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
• Path parameters (:userId, :id, etc.)
• Query parameters accessed via req.query.paramName
• Body parameters accessed via req.body.fieldName
• Form-data detection (when req.file or req.files is used)
• Route grouping by base path

🔄 Coming Soon

• TypeScript support
• JSDoc comment parsing for descriptions
• Request/response examples
• Authentication/authorization detection
• Validation schema extraction (express-validator, Joi, etc.)
• Environment variables

Importing to Postman

1. Open Postman
2. Click "Import" button
3. Select the generated .postman_collection.json file
4. Start testing your API! 🎉

Programmatic Usage

You can also use the generator programmatically in your Node.js scripts:

const PostmanGenerator = require('express-postman-generator');

async function generateCollection() {
  const generator = new PostmanGenerator({
    projectPath: './my-express-app',
    collectionName: 'My API',
    baseUrl: 'http://localhost:3000',
    outputPath: './api-collection.json'
  });

  const outputPath = await generator.generate();
  console.log(`Collection saved to: ${outputPath}`);
}

generateCollection();

Troubleshooting

No routes found

• Make sure your route files use standard Express.js syntax
• Check that your files match the include patterns
• Verify files aren't excluded by exclude patterns

Missing parameters

• The generator detects parameters by analyzing req.body, req.query, and req.params usage
• Make sure you're accessing these properties in your route handlers
• For better detection, destructure parameters in the handler function

Incorrect body type

• The generator defaults to JSON for POST/PUT/PATCH
• If you use req.file or req.files, it will detect form-data
• You can manually adjust the collection after generation if needed

Contributing

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

License

MIT

Author

Created to make API documentation easier for Express.js developers! 🚀

Made with ❤️ for backend developers who hate writing API docs