Laravel Api To Postman Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the package:

   composer require andreaselia/laravel-api-to-postman
   

2. Publish the config:

   php artisan vendor:publish --provider="AndreasElia\PostmanGenerator\PostmanGeneratorServiceProvider"
   

   This creates config/api-postman.php in your project.

3. Run the generator (basic usage):

   php artisan export:postman
   

   Outputs a Postman collection JSON file to storage/app/.

4. Import into Postman:

   • Open Postman → Import → Upload the generated JSON file.

First Use Case: Quick API Documentation

For a Laravel API with routes like:

Route::get('/users', [UserController::class, 'index']);
Route::post('/users', [UserController::class, 'store']);

Run:

php artisan export:postman --bearer="your_token_here"

This generates a Postman collection with:

• GET /users (no auth if route is public).
• POST /users (with Bearer token for protected routes).

Implementation Patterns

1. Workflow Integration

CI/CD Pipeline (GitHub Actions Example)

# .github/workflows/generate-postman.yml
name: Generate Postman Collection
on: [push]
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install -n --prefer-dist
      - run: php artisan export:postman --bearer="${{ secrets.API_TOKEN }}"
      - uses: actions/upload-artifact@v3
        with:
          name: postman-collection
          path: storage/app/*.json

Use Case: Auto-generate collections on every main branch push, attach as an artifact for QA teams.

2. Auth Handling

Bearer Token (Recommended for JWT)

php artisan export:postman --bearer="1|abc123xyz456"

• Config: Set auth_type to bearer in api-postman.php.
• Dynamic Tokens: Use environment variables:

  php artisan export:postman --bearer="$BEARER_TOKEN"
  

Basic Auth (Legacy APIs)

php artisan export:postman --basic="admin:password123"

• Config: Set auth_type to basic.
• Note: Bearer auth takes precedence if both are provided.

3. FormRequest Rule Scaffolding

Enable in Config

'form_request' => [
    'enabled' => true,
    'format' => 'human', // or 'raw'
],

Example Route with FormRequest

Route::post('/users', [UserController::class, 'store'])
    ->middleware('auth:sanctum');

Output: Postman request body includes:

{
  "name": "required|string|max:255",
  "email": "required|email|unique:users"
}

Use Case: Reduces manual request body setup for API consumers.

4. Structured Collections

Group Routes by Prefix

// config/api-postman.php
'group_by_prefix' => true,

Example Output:

📁 /api/v1
├── 📄 GET /users
├── 📄 POST /users
└── 📁 /admin
    └── 📄 GET /stats

5. Excluding Routes

Skip Specific Routes

// config/api-postman.php
'exclude' => [
    'admin.*', // Regex pattern
    'webhook.*',
],

Use Case: Exclude internal routes (e.g., webhooks) from public collections.

Gotchas and Tips

Pitfalls

1. Auth Mismatch Errors

   • Issue: Routes with auth:sanctum may fail if --bearer is omitted.
   • Fix: Always specify auth flags or set default_auth in config:

     'default_auth' => [
         'type' => 'bearer',
         'token' => env('POSTMAN_BEARER_TOKEN'),
     ],
     

2. FormRequest Rules Not Showing

   • Issue: Rules from FormRequest classes may not appear.
   • Fix: Ensure:
     • form_request.enabled = true in config.
     • The route uses a FormRequest (not manual validation).

3. Path Parameters Dropped

   • Issue: Routes like /users/{id} may lose {id} in Postman.
   • Fix: Update config/api-postman.php:

     'path_parameters' => true,
     

4. Collection Merging Bugs

   • Issue: Running export:postman multiple times may duplicate entries.
   • Fix: Use --force to overwrite or set continue_on_errors = true.

Debugging Tips

1. Inspect Generated JSON

   php artisan export:postman --debug
   

   Outputs raw JSON to storage/logs/postman-debug.json.

2. Validate Postman Schema Use Postman’s Schema Validator to check for malformed entries.

3. Check Route Registration Run:

   php artisan route:list
   

   Ensure your API routes are registered before export.

Extension Points

1. Customize Request Descriptions Override the description field in config/api-postman.php:

   'description_template' => 'API Endpoint: {{ route }} | Method: {{ method }}',
   

2. Add Headers/Variables Extend the PostmanGenerator class to inject custom headers:

   // app/Providers/PostmanServiceProvider.php
   public function boot()
   {
       $generator = app(AndreasElia\PostmanGenerator\PostmanGenerator::class);
       $generator->addHeader('X-Custom-Header', 'value');
   }
   

3. Support for OpenAPI Workaround: Use the generated Postman collection as a reference to build OpenAPI specs manually or via tools like Postman to OpenAPI converters.

4. Dynamic Environment Variables Use Laravel’s env() in config:

   'auth' => [
       'type' => 'bearer',
       'token' => env('POSTMAN_DYNAMIC_TOKEN', 'default_token'),
   ],
   

Pro Tips

• Version Control: Commit the generated Postman collection to your repo (e.g., storage/app/postman-collection.json) to track API changes over time.
• Postman Environments: Use the --bearer flag with environment variables to switch between dev/prod tokens.
• API Changelogs: Combine with laravel-shift/doctrine to auto-generate changelogs for API consumers.
• Performance: For large APIs (>500 routes), disable form_request and group_by_prefix to speed up generation.