Automatically generate Postman collections from your Laravel API routes with flexible organization and authentication support.
- Generate Postman collections with one command
- Automatic request body generation from FormRequest validation rules
- Multiple organization strategies (route prefix, controller, nested paths)
- Built-in authentication support (Bearer, Basic Auth, API Keys)
- Customizable route filtering
- Environment variable support for sensitive data
Install via Composer:
composer require --dev yasin_tgh/laravel-postmanPublish the config file:
php artisan vendor:publish --provider="YasinTgh\LaravelPostman\PostmanServiceProvider" --tag="postman-config"Generate documentation:
php artisan postman:generateThe collection will be saved to: storage/postman/api_collection.json
Configure how API routes are organized in Postman folders, how request names are formatted, and how request bodies are generated, including optional default values for fields.
'structure' => [
'folders' => [
'strategy' => 'nested_path', // 'prefix', 'nested_path', or 'controller'
'max_depth' => 3, // Only for nested_path strategy
'mapping' => [
'admin' => 'Administration' // Custom folder name mapping
]
],
'naming_format' => '[{method}] {uri}', // placeholders: {method} {uri} {controller} {action}
/**
* Request body settings:
* - default_body_type: 'raw' or 'formdata'
* - default_values: preset values applied to generated fields
*/
'requests' => [
'default_body_type' => 'raw',
'default_values' => [
// 'email' => 'test@example.com',
// 'password' => '123456',
],
],
]Control which routes are included:
'routes' => [
'prefix' => 'api', // Base API prefix
'include' => [
'patterns' => ['api/users/*'], // Wildcard patterns
'middleware' => ['api'], // Only routes with these middleware
'controllers' => [App\Http\Controllers\UserController::class] // Specific controllers
],
'exclude' => [
'patterns' => ['admin/*'],
'middleware' => ['debug'],
'controllers' => [App\Http\Controllers\TestController::class]
]
]Document your API authentication:
'auth' => [
'enabled' => true,
'type' => 'bearer', // 'bearer', 'basic', or 'api_key'
'location' => 'header', // 'header' or 'query' for API keys
'default' => [
'token' => env('POSTMAN_AUTH_TOKEN'),
'username' => env('POSTMAN_AUTH_USER'),
'password' => env('POSTMAN_AUTH_PASSWORD'),
'key_name' => 'X-API-KEY',
'key_value' => env('POSTMAN_API_KEY')
],
'protected_middleware' => ['auth:api', 'auth:sanctum']
]'output' => [
'driver' => env('POSTMAN_STORAGE_DISK', 'local'),
// Storage path for generated files
'path' => env('POSTMAN_STORAGE_DIR', storage_path('postman')),
// File naming pattern (date will be appended)
'filename' => env('POSTMAN_STORAGE_FILE', 'api_collection'),
],'auth' => [
'enabled' => true,
'type' => 'bearer',
'default' => [
'token' => 'your-bearer-token'
]
]'auth' => [
'enabled' => true,
'type' => 'basic',
'default' => [
'username' => 'api-user',
'password' => 'secret'
]
]'auth' => [
'enabled' => true,
'type' => 'api_key',
'location' => 'header', // or 'query'
'default' => [
'key_name' => 'X-API-KEY',
'key_value' => 'your-api-key-123'
]
]Use .env values for sensitive data:
'auth' => [
'default' => [
'token' => env('POSTMAN_DEMO_TOKEN', 'test-token')
]
]Generated Postman collection will:
- Group routes by your chosen strategy
- Apply authentication to protected routes
- Include all configured headers
- Use variables for base URL and auth credentials
{
"info": {
"name": "My API",
"description": "API Documentation"
},
"variable": [
{"key": "base_url", "value": "https://api.example.com"},
{"key": "auth_token", "value": "your-token"}
],
"item": [
{
"name": "[GET] users",
"request": {
"method": "GET",
"body": {
"mode": "raw",
"raw": "{\"email\":\"user@example.com\",\"password\":\"password123\"}"
},
"auth": {
"type": "bearer",
"bearer": [{"key": "token", "value": "{{auth_token}}"}]
}
}
}
]
}- Generate a Postman API key at go.postman.co/settings/me/api-keys.
- Get the Collection ID with either method below.
Option A — Postman API (recommended)
List every collection on the account and copy uid (or id) for the collection you want to sync:
curl --location 'https://api.getpostman.com/collections' \
--header 'X-Api-Key: YOUR_POSTMAN_API_KEY'Example response:
{
"collections": [
{
"id": "12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "My Phobia",
"uid": "12345678-12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
]
}Use the uid value as POSTMAN_COLLECTION_ID. Match on "name" if you have more than one collection.
To print name + uid only:
curl --location 'https://api.getpostman.com/collections' \
--header 'X-Api-Key: YOUR_POSTMAN_API_KEY' \
| php -r '$d=json_decode(stream_get_contents(STDIN), true); foreach (($d["collections"] ?? []) as $c) { echo $c["name"]." => ".$c["uid"].PHP_EOL; }'Option B — Postman app
Open the collection → ⋯ → Info → copy Collection ID.
Add to your .env:
POSTMAN_API_KEY=PMAK-xxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
POSTMAN_COLLECTION_ID=12345678-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
POSTMAN_WORKSPACE_ID= # optionalPublish and update config/postman.php:
'cloud' => [
'api_key' => env('POSTMAN_API_KEY'),
'collection_id' => env('POSTMAN_COLLECTION_ID'),
'workspace_id' => env('POSTMAN_WORKSPACE_ID'),
'merge' => [
'preserve_responses' => true, // keep saved example responses
'preserve_scripts' => true, // keep pre-request & test scripts
'preserve_manual_items' => true, // keep manually added routes/folders
'overwrite_descriptions' => false, // keep descriptions written in Postman UI
],
],# Generate locally only
php artisan postman:generate
# Generate + push incremental changes to Postman Cloud
php artisan postman:generate --push
# Preview the merge result without pushing (useful in CI)
php artisan postman:generate --dry-run| Item | Behaviour |
|---|---|
| New Laravel routes | Added to the matching folder in the remote collection |
| Changed route method / path | Updated automatically |
| Updated FormRequest body fields | Updated automatically |
| Saved example responses | Preserved (preserve_responses) |
| Pre-request & test scripts | Preserved (preserve_scripts) |
| Manually added Postman routes | Preserved (preserve_manual_items) |
| Descriptions written in Postman | Preserved by default (overwrite_descriptions: false) |
| Collection variables | Existing remote variables are never overwritten; new ones are appended |
Pull requests are welcome! For major changes, please open an issue first.