Skip to main content

Installation and Configuration

This guide provides detailed instructions from installing Laravel Spectrum to initial configuration.

📋 Requirements​

  • PHP 8.1 or higher
  • Laravel 10.x, 11.x, 12.x
  • Composer 2.0 or higher

🚀 Installation​

Laravel 11 Setup​

For Laravel 11, you need to install API routes first if they're not already present:

php artisan install:api

This command:

  • Installs Laravel Sanctum
  • Creates the routes/api.php file
  • Configures API authentication

Install via Composer​

composer require wadakatu/laravel-spectrum --dev

Laravel Auto-Discovery​

For Laravel 5.5 and above, the service provider is automatically registered.

⚙️ Publishing Configuration​

To customize the default configuration, publish the config file:

php artisan vendor:publish --provider="LaravelSpectrum\SpectrumServiceProvider" --tag="config"

This creates a config/spectrum.php file.

🔧 Basic Configuration​

API Basic Information​

// config/spectrum.php
return [
    'title' => env('APP_NAME', 'Laravel') . ' API',
    'version' => '1.0.0',
    'description' => 'API documentation generated by Laravel Spectrum',
];

Route Patterns​

Specify route patterns to include in documentation:

'route_patterns' => [
    'api/*',
    'api/v1/*',
    'api/v2/*',
],

Excluded Routes​

To exclude specific routes from documentation:

'excluded_routes' => [
    'api/health',
    'api/ping',
    '_debugbar/*',
],

🔐 Authentication Configuration​

Bearer Token (JWT/Sanctum)​

'authentication' => [
    'default' => 'bearer',
    'flows' => [
        'bearer' => [
            'type' => 'http',
            'scheme' => 'bearer',
            'bearerFormat' => 'JWT',
        ],
    ],
],

API Key Authentication​

'authentication' => [
    'default' => 'api_key',
    'flows' => [
        'api_key' => [
            'type' => 'apiKey',
            'in' => 'header',
            'name' => 'X-API-Key',
        ],
    ],
],

🎨 Customization​

Tag Configuration​

Tag mapping for organizing endpoints:

'tags' => [
    'api/v1/auth/*' => 'Authentication',
    'api/v1/users/*' => 'User Management',
    'api/v1/posts/*' => 'Blog Posts',
    'api/v1/admin/*' => 'Administration',
],

Customizing Response Examples​

'example_generation' => [
    'use_faker' => true,
    'faker_locale' => 'en_US',
    'faker_seed' => 12345, // Generate consistent example data
    'custom_generators' => [
        'status' => fn($faker) => $faker->randomElement(['active', 'inactive']),
        'role' => fn($faker) => $faker->randomElement(['admin', 'user']),
    ],
],

📁 Output Configuration​

Changing Output Location​

'output' => [
    'openapi' => storage_path('app/public/api-docs/openapi.json'),
    'postman' => storage_path('app/public/api-docs/postman.json'),
    'insomnia' => storage_path('app/public/api-docs/insomnia.json'),
],

Cache Configuration​

For performance improvement in large projects:

'cache' => [
    'enabled' => true,
    'ttl' => 3600, // 1 hour
    'directory' => storage_path('app/spectrum/cache'),
],

⚠️ Important Notes​

Controller-Based Routes Only​

Laravel Spectrum only supports controller-based routes. Closure routes are not supported:

// ❌ NOT SUPPORTED - Closure route
Route::get('/api/test', function () {
    return ['message' => 'test'];
});

// ✅ SUPPORTED - Controller route
Route::get('/api/test', [TestController::class, 'index']);

To convert closure routes to controller routes:

  1. Create a controller: php artisan make:controller Api/TestController
  2. Move the closure logic to the controller method
  3. Update the route to use the controller

Configuration File​

If the configuration file is not published automatically, copy it manually:

cp vendor/wadakatu/laravel-spectrum/config/spectrum.php config/spectrum.php

Route Pattern Matching​

Use wildcards correctly in route patterns:

'route_patterns' => [
    'api/*',     // Matches api/users, api/posts
    'api/**',    // For nested paths (may not work with all versions)
    'api/v1/*',  // Matches api/v1/users, api/v1/posts
],

🚨 Troubleshooting​

Permission Errors​

Check write permissions for storage directories:

chmod -R 775 storage
chmod -R 775 bootstrap/cache

Routes Not Detected​

  1. Clear route cache:

    php artisan route:clear

  2. Verify route patterns are correct:

    // config/spectrum.php
    'route_patterns' => [
        'api/*', // All API routes
    ],

📚 Next Steps​