README

The most advanced Laravel Postman collection generator.
Import and start testing immediately - zero manual configuration required.

Why This Package?

Existing packages generate a JSON file and leave you to configure everything manually. This package generates a production-ready collection with auto-generated test scripts, realistic sample data from your factories, example API responses, and a beautiful browser documentation page - all working out of the box.

What Makes This Different

Requirements

• PHP 8.1+
• Laravel 10.x, 11.x, 12.x, or 13.x

Installation

composer require programmersbeats/postman-generator --dev

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

Quick Start

# Generate a single collection file (ready to import)
php artisan postman:collection --Bearer -n

That's it. Import the single file into Postman and start testing. Everything is embedded - no separate environment file needed.

Output files are auto-versioned:

storage/postman/neorecruits-api-2026-v1.postman_collection.json   (1st run)
storage/postman/neorecruits-api-2026-v2.postman_collection.json   (2nd run)
storage/postman/neorecruits-api-2026-v3.postman_collection.json   (3rd run)

Then visit http://your-app.test/api-documentation to view your docs in the browser.

Feature 1: Auto-Generated Test Scripts

Every endpoint in your collection gets automatic Postman test scripts. No other package does this.

Generated tests include:

• Status code validation (200, 201, 204 based on HTTP method)
• Response time check (under 2 seconds)
• Content-Type JSON validation
• Response structure validation (data array for index, data object for show)
• Validation error detection for POST/PUT/PATCH
• Auth token validity check for protected routes

Example test script auto-generated for a GET /api/users endpoint:

pm.test('Status code is 200', function () {
    pm.response.to.have.status(200);
});

pm.test('Response time is acceptable', function () {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

pm.test('Response is valid JSON', function () {
    pm.response.to.be.json;
});

pm.test('Response has data array (paginated)', function () {
    const json = pm.response.json();
    if (json.data !== undefined) {
        pm.expect(json.data).to.be.an('array');
    }
});

Disable with --no-tests if not needed.

Feature 2: Example Responses from API Resources

The package parses your JsonResource classes and generates realistic example response bodies embedded directly in the collection.

If your controller returns:

public function show(User $user): UserResource
{
    return new UserResource($user);
}

And your UserResource has:

public function toArray($request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'created_at' => $this->created_at,
    ];
}

The collection will include an example response:

{
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "user@example.com",
        "created_at": "2026-01-15T10:30:00.000000Z"
    }
}

Disable with --no-responses if not needed.

Feature 3: Realistic Request Data from Model Factories

Instead of generic "sample_value" placeholders, request bodies are populated with realistic data parsed from your Model Factories.

If your UserFactory has:

public function definition(): array
{
    return [
        'name' => fake()->name(),
        'email' => fake()->safeEmail(),
        'password' => Hash::make('password'),
    ];
}

The POST body becomes:

{
    "name": "John Doe",
    "email": "user@example.com",
    "password": "password123"
}

Faker methods are mapped to realistic sample values (100+ methods supported). Disable with --no-factory.

Feature 4: Single File, Zero-Config

Everything is embedded in one collection file - no separate environment file needed. The collection includes your actual APP_URL as pre-configured variables:

• {{base_url}} - Auto-set to your APP_URL/api
• {{Bearer}} - Token stored automatically after login
• {{token_expiry}} - Token expiry tracking
• {{app_url}} - Your application URL

Import one file -> Start testing. No configuration steps.

Feature 5: API Changelog (postman:diff)

Compare your current routes against the last generated collection to see what changed.

php artisan postman:diff

Output:

+ 3 New Endpoint(s):
  + [POST] api/auth/2fa/enable
  + [POST] api/auth/2fa/confirm
  + [GET]  api/auth/2fa/recovery-codes

- 1 Removed Endpoint(s):
  - [POST] api/auth/verify-email

~ 1 Modified Endpoint(s):
  ~ [PUT] api/users/{user}
      Now requires authentication

Summary:
  Added:    3
  Removed:  1
  Modified: 1
  Total:    24 endpoints

Save as markdown report:

php artisan postman:diff --output=CHANGELOG-api.md

Feature 6: Browser API Documentation

Visit /api-documentation for a beautiful, interactive documentation page.

Page features:

• Dark sidebar with collapsible nested folder navigation
• Color-coded HTTP method badges (GET, POST, PUT, PATCH, DELETE)
• Real-time search across all endpoints (press / to focus)
• Expandable route cards with full details
• Copy-as-cURL button for every endpoint
• Example response display inline
• Rate limit information from throttle middleware
• Auth/public route indicators
• Responsive + print support

Feature 7: Nested Folder Structure

Route prefixes create hierarchical Postman folders:

Route::prefix('auth/pin')->group(function () {
    Route::post('set', [PinController::class, 'setPin']);
    Route::put('update', [PinController::class, 'updatePin']);
});

Route::prefix('auth/2fa')->group(function () {
    Route::post('enable', [TwoFactorSetupController::class, 'enable']);
    Route::post('confirm', [TwoFactorSetupController::class, 'confirm']);
});

Produces:

Auth/
  Pin/
    Set Pin
    Update Pin
  2fa/
    Enable
    Confirm

Customize folder names:

'grouping' => [
    'folder_names' => [
        'auth'      => 'Authentication',
        'auth/pin'  => 'PIN Management',
        'auth/2fa'  => '2FA Setup',
    ],
],

Feature 8: Multi-Route-File Support

Automatically discovers routes from all registered files. Works with Laravel 11's bootstrap/app.php:

->withRouting(
    api: __DIR__.'/../routes/api.php',
    then: function () {
        Route::middleware('api')->prefix('api')
            ->group(base_path('routes/candidate.php'));
        Route::middleware('api')->prefix('api')
            ->group(base_path('routes/admin.php'));
    },
)

All routes from every file appear in the collection and documentation.

Feature 9: cURL Commands

Every endpoint includes a ready-to-use cURL command in both the Postman collection description and the browser documentation:

curl -X POST \
  'http://your-app.test/api/auth/login' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

Feature 10: Rate Limit Documentation

Throttle middleware is automatically parsed and displayed:

Route::middleware('throttle:60,1')->group(function () {
    // Routes here show "60 requests per 1 minute(s)" in docs
});

Command Flags

php artisan postman:collection

php artisan postman:diff

Examples

# Full collection with Bearer auth (non-interactive)
php artisan postman:collection --Bearer -n

# Interactive mode - guided setup with prompts
php artisan postman:collection

# Custom name and controller grouping
php artisan postman:collection --Bearer --name="My API v2" --strategy=controller -n

# Minimal collection without test scripts
php artisan postman:collection --Bearer --minimal --no-tests -n

# Compare routes with last generated collection
php artisan postman:diff

# Save API changelog as markdown
php artisan postman:diff --output=API-CHANGELOG.md

Grouping Strategies

Configuration

// config/postman-generator.php

'features' => [
    'test_scripts' => true,        // Auto-generate Postman test scripts
    'example_responses' => true,    // Generate example responses from Resources
    'factory_data' => true,         // Use Factory data for request bodies
],

'documentation' => [
    'enabled' => true,
    'route' => 'api-documentation',
    'middleware' => ['web'],
],

'grouping' => [
    'default' => 'prefix',
    'folder_names' => [
        // 'auth/pin' => 'PIN Management',
    ],
],

Publishing & Customization

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

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security

If you discover any security-related issues, please email programmersbeats@gmail.com instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

Credits

• Ameer Hamza
• All Contributors

Support

If you find this package helpful, consider supporting ProgrammersBeats by starring the repository and sharing it with your network.