README

A smart Postman collection generator for Laravel 11.x and 12.x that automatically scans routes, extracts metadata from attributes/docblocks, and generates realistic request body examples from FormRequests.

Features

• Automated Scanning: Automatically finds all API routes.
• Metadata Extraction: Derives request names, descriptions, and folders from #[PostmanMeta] attributes or DocBlocks.
• Body Example Generation: Parses FormRequest validation rules (including nested and wildcard rules) to create non-empty JSON/form-data bodies.
• Response Capture: Optionally hits your local endpoints to capture live response examples.
• Smart Grouping: Groups requests into folders based on URI segments or Controller names.
• Auth Detection: Automatically detects Bearer authentication from middlewares.

Installation

composer require laravelgenerators/postman-generator:main-dev

The package uses Laravel's auto-discovery, so it's ready to use immediately.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=postman-generator-config

Key Options

In config/postman-generator.php:

• collection_name: The name of your imported collection.
• base_url: Defaults to your APP_URL, used as {{base_url}} variable.
• auto_examples: Set to true (default) to generate bodies from FormRequests.
• generate_responses: Set to true to capture live responses (local-only for safety).

Local Response Capture

If generate_responses is enabled, define a token in your .env for authenticated requests:

POSTMAN_GENERATOR_TOKEN=your-local-dev-bearer-token

Usage

Generate the collection JSON:

php artisan postman:generate

Override output path:

php artisan postman:generate --output=path/to/my-collection.json

Annotating Routes

Use the #[PostmanMeta] attribute for precise control. You can also override the request body for routes that don't use FormRequests (e.g., when using $request->validate() directly):

use LaravelGenerators\PostmanGenerator\Attributes\PostmanMeta;

class OrderController extends Controller
{
    #[PostmanMeta(
        name: 'List All Orders', 
        folder: 'Order Management', 
        description: 'Returns a paginated list of orders',
        body: ['email' => 'user@example.com', 'password' => 'secret']
    )]
    public function index() { ... }
}

Or use DocBlock tags (body must be valid JSON):

/**
 * @postman-name List All Orders
 * @postman-folder Order Management
 * @postman-body {"email": "user@example.com", "password": "secret"}
 */
public function index() { ... }

License

The MIT License (MIT).