Skip to main content

Configuration Reference

A detailed reference of all configuration options in the config/spectrum.php file.

📋 Publishing the Configuration File​

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

🔧 Basic Configuration​

API Information​

/*
|--------------------------------------------------------------------------
| API Documentation Title
|--------------------------------------------------------------------------
|
| The title of your API documentation. Displayed at the top of the documentation.
|
*/
'title' => env('APP_NAME', 'Laravel') . ' API',

/*
|--------------------------------------------------------------------------
| API Version
|--------------------------------------------------------------------------
|
| The version of your API. Included in the OpenAPI specification.
|
*/
'version' => '1.0.0',

/*
|--------------------------------------------------------------------------
| API Description
|--------------------------------------------------------------------------
|
| The description of your API. Can be written in Markdown format.
|
*/
'description' => 'API documentation generated by Laravel Spectrum',

/*
|--------------------------------------------------------------------------
| Terms of Service URL
|--------------------------------------------------------------------------
|
| The URL to your terms of service (optional).
|
*/
'terms_of_service' => 'https://example.com/terms',

/*
|--------------------------------------------------------------------------
| Contact Information
|--------------------------------------------------------------------------
|
| Contact information for the API provider.
|
*/
'contact' => [
    'name' => 'API Support',
    'email' => 'api@example.com',
    'url' => 'https://example.com/support',
],

/*
|--------------------------------------------------------------------------
| License Information
|--------------------------------------------------------------------------
|
| License information for your API.
|
*/
'license' => [
    'name' => 'MIT',
    'url' => 'https://opensource.org/licenses/MIT',
],

Server Configuration​

/*
|--------------------------------------------------------------------------
| Servers
|--------------------------------------------------------------------------
|
| List of API servers. You can define multiple environments.
|
*/
'servers' => [
    [
        'url' => env('APP_URL', 'http://localhost'),
        'description' => 'Development server',
    ],
    [
        'url' => 'https://staging.example.com',
        'description' => 'Staging server',
    ],
    [
        'url' => 'https://api.example.com',
        'description' => 'Production server',
    ],
],

📂 Route Configuration​

/*
|--------------------------------------------------------------------------
| Route Patterns
|--------------------------------------------------------------------------
|
| Patterns of routes to include in documentation. You can use wildcards (*).
|
*/
'route_patterns' => [
    'api/*',
    'api/v1/*',
    'api/v2/*',
],

/*
|--------------------------------------------------------------------------
| Excluded Routes
|--------------------------------------------------------------------------
|
| Specific routes to exclude from documentation.
|
*/
'excluded_routes' => [
    'api/health',
    'api/ping',
    'api/debug/*',
    '_debugbar/*',
    'telescope/*',
    'horizon/*',
],

/*
|--------------------------------------------------------------------------
| Route Metadata
|--------------------------------------------------------------------------
|
| Add additional metadata to routes.
|
*/
'route_metadata' => [
    'api/admin/*' => [
        'deprecated' => true,
        'x-internal' => true,
    ],
],

🏷️ Tag Configuration​

/*
|--------------------------------------------------------------------------
| Tag Mappings
|--------------------------------------------------------------------------
|
| Tag mappings for grouping routes.
| You can use exact matches or wildcards (*).
|
*/
'tags' => [
    // Exact matches
    'api/v1/auth/login' => 'Authentication',
    'api/v1/auth/logout' => 'Authentication',
    'api/v1/auth/refresh' => 'Authentication',
    
    // Wildcards
    'api/v1/users/*' => 'User Management',
    'api/v1/posts/*' => 'Blog Posts',
    'api/v1/admin/*' => 'Administration',
    'api/v1/reports/*' => 'Reports',
],

/*
|--------------------------------------------------------------------------
| Tag Descriptions
|--------------------------------------------------------------------------
|
| Description for each tag.
|
*/
'tag_descriptions' => [
    'Authentication' => 'Authentication and authorization endpoints',
    'User Management' => 'Create, read, update, and delete users',
    'Blog Posts' => 'Manage blog posts',
    'Administration' => 'Admin-only endpoints',
],

/*
|--------------------------------------------------------------------------
| Tag Order
|--------------------------------------------------------------------------
|
| Display order for tags. Tags not in the list are displayed alphabetically.
|
*/
'tag_order' => [
    'Authentication',
    'User Management',
    'Blog Posts',
    'Administration',
],

🔐 Authentication Configuration​

/*
|--------------------------------------------------------------------------
| Authentication Configuration
|--------------------------------------------------------------------------
|
| Configuration for API authentication methods.
|
*/
'authentication' => [
    /*
    |--------------------------------------------------------------------------
    | Default Authentication
    |--------------------------------------------------------------------------
    |
    | The default authentication method.
    |
    */
    'default' => 'bearer',
    
    /*
    |--------------------------------------------------------------------------
    | Authentication Flows
    |--------------------------------------------------------------------------
    |
    | Definition of available authentication flows.
    |
    */
    'flows' => [
        'bearer' => [
            'type' => 'http',
            'scheme' => 'bearer',
            'bearerFormat' => 'JWT',
            'description' => 'JWT Bearer Token authentication',
        ],
        
        'apiKey' => [
            'type' => 'apiKey',
            'in' => 'header',
            'name' => 'X-API-Key',
            'description' => 'API Key authentication',
        ],
        
        'basic' => [
            'type' => 'http',
            'scheme' => 'basic',
            'description' => 'Basic authentication',
        ],
        
        'oauth2' => [
            'type' => 'oauth2',
            'flows' => [
                'authorizationCode' => [
                    'authorizationUrl' => '/oauth/authorize',
                    'tokenUrl' => '/oauth/token',
                    'refreshUrl' => '/oauth/token/refresh',
                    'scopes' => [
                        'read' => 'Read permission',
                        'write' => 'Write permission',
                        'delete' => 'Delete permission',
                    ],
                ],
            ],
        ],
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Middleware Mapping
    |--------------------------------------------------------------------------
    |
    | Mapping between Laravel middleware and authentication flows.
    |
    */
    'middleware_map' => [
        'auth' => 'bearer',
        'auth:api' => 'bearer',
        'auth:sanctum' => 'bearer',
        'auth:passport' => 'oauth2',
        'auth.basic' => 'basic',
        'api-key' => 'apiKey',
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Exclude Patterns
    |--------------------------------------------------------------------------
    |
    | Route patterns that don't require authentication.
    |
    */
    'exclude_patterns' => [
        'api/health',
        'api/status',
        'api/auth/login',
        'api/auth/register',
        'api/password/forgot',
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Global Security
    |--------------------------------------------------------------------------
    |
    | Whether to apply global security to all endpoints.
    |
    */
    'global_security' => false,
],

🎨 Example Data Generation​

/*
|--------------------------------------------------------------------------
| Example Generation
|--------------------------------------------------------------------------
|
| Configuration for generating request/response examples.
|
*/
'example_generation' => [
    /*
    |--------------------------------------------------------------------------
    | Use Faker
    |--------------------------------------------------------------------------
    |
    | Whether to use Faker to generate realistic example data.
    |
    */
    'use_faker' => env('SPECTRUM_USE_FAKER', true),
    
    /*
    |--------------------------------------------------------------------------
    | Faker Locale
    |--------------------------------------------------------------------------
    |
    | Faker locale setting.
    |
    */
    'faker_locale' => env('SPECTRUM_FAKER_LOCALE', 'en_US'),
    
    /*
    |--------------------------------------------------------------------------
    | Faker Seed
    |--------------------------------------------------------------------------
    |
    | Seed value for generating consistent example data.
    |
    */
    'faker_seed' => env('SPECTRUM_FAKER_SEED', null),
    
    /*
    |--------------------------------------------------------------------------
    | Custom Field Generators
    |--------------------------------------------------------------------------
    |
    | Custom generators for specific field names.
    |
    */
    'custom_generators' => [
        'email' => fn($faker) => $faker->safeEmail(),
        'phone' => fn($faker) => $faker->phoneNumber(),
        'avatar_url' => fn($faker) => $faker->imageUrl(200, 200, 'people'),
        'price' => fn($faker) => $faker->randomFloat(2, 100, 10000),
        'status' => fn($faker) => $faker->randomElement(['active', 'inactive', 'pending']),
        'role' => fn($faker) => $faker->randomElement(['admin', 'user', 'guest']),
        'country_code' => fn($faker) => $faker->countryCode(),
        'currency' => fn($faker) => $faker->currencyCode(),
        'latitude' => fn($faker) => $faker->latitude(),
        'longitude' => fn($faker) => $faker->longitude(),
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Array Limits
    |--------------------------------------------------------------------------
    |
    | Number of elements to generate for array examples.
    |
    */
    'array_limits' => [
        'min' => 1,
        'max' => 3,
    ],
],

⚡ Performance Configuration​

/*
|--------------------------------------------------------------------------
| Performance Configuration
|--------------------------------------------------------------------------
|
| Performance optimization settings.
|
*/
'performance' => [
    /*
    |--------------------------------------------------------------------------
    | Enable Optimization
    |--------------------------------------------------------------------------
    |
    | Whether to enable performance optimization.
    |
    */
    'enabled' => true,
    
    /*
    |--------------------------------------------------------------------------
    | Parallel Processing
    |--------------------------------------------------------------------------
    |
    | Parallel processing configuration.
    |
    */
    'parallel_processing' => true,
    'workers' => env('SPECTRUM_WORKERS', 'auto'), // 'auto' for CPU cores
    'chunk_size' => env('SPECTRUM_CHUNK_SIZE', 100),
    'memory_limit' => env('SPECTRUM_MEMORY_LIMIT', '512M'),
    
    /*
    |--------------------------------------------------------------------------
    | Analysis Optimization
    |--------------------------------------------------------------------------
    |
    | Analysis optimization settings.
    |
    */
    'analysis' => [
        'max_depth' => 3,
        'skip_vendor' => true,
        'lazy_loading' => true,
        'use_cache' => true,
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Resource Limits
    |--------------------------------------------------------------------------
    |
    | Resource limits.
    |
    */
    'limits' => [
        'max_routes' => 10000,
        'max_file_size' => '50M',
        'timeout' => 300,
        'max_schema_depth' => 10,
    ],
],

💾 Cache Configuration​

/*
|--------------------------------------------------------------------------
| Cache Configuration
|--------------------------------------------------------------------------
|
| Cache settings.
|
*/
'cache' => [
    /*
    |--------------------------------------------------------------------------
    | Enable Cache
    |--------------------------------------------------------------------------
    |
    | Whether to enable caching.
    |
    */
    'enabled' => env('SPECTRUM_CACHE_ENABLED', true),
    
    /*
    |--------------------------------------------------------------------------
    | Cache Store
    |--------------------------------------------------------------------------
    |
    | The cache store to use.
    |
    */
    'store' => env('SPECTRUM_CACHE_STORE', 'file'),
    
    /*
    |--------------------------------------------------------------------------
    | Cache Directory
    |--------------------------------------------------------------------------
    |
    | Directory for file cache.
    |
    */
    'directory' => storage_path('app/spectrum/cache'),
    
    /*
    |--------------------------------------------------------------------------
    | Cache TTL
    |--------------------------------------------------------------------------
    |
    | Cache expiration time in seconds. null for indefinite.
    |
    */
    'ttl' => env('SPECTRUM_CACHE_TTL', null),
    
    /*
    |--------------------------------------------------------------------------
    | Cache Segments
    |--------------------------------------------------------------------------
    |
    | Cache configuration by segment.
    |
    */
    'segments' => [
        'routes' => ['ttl' => 86400], // 24 hours
        'schemas' => ['ttl' => 3600], // 1 hour
        'examples' => ['ttl' => 7200], // 2 hours
        'analysis' => ['ttl' => 3600], // 1 hour
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Watch Files
    |--------------------------------------------------------------------------
    |
    | Files to watch for changes to invalidate cache.
    |
    */
    'watch_files' => [
        base_path('composer.json'),
        base_path('composer.lock'),
        config_path('spectrum.php'),
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Smart Invalidation
    |--------------------------------------------------------------------------
    |
    | Whether to enable smart cache invalidation.
    |
    */
    'smart_invalidation' => true,
],

👁️ Watch Configuration​

/*
|--------------------------------------------------------------------------
| Watch Configuration
|--------------------------------------------------------------------------
|
| File watching configuration.
|
*/
'watch' => [
    /*
    |--------------------------------------------------------------------------
    | Watch Paths
    |--------------------------------------------------------------------------
    |
    | Directories and files to watch.
    |
    */
    'paths' => [
        app_path('Http/Controllers'),
        app_path('Http/Requests'),
        app_path('Http/Resources'),
        base_path('routes'),
        config_path(),
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Ignore Patterns
    |--------------------------------------------------------------------------
    |
    | File patterns to ignore.
    |
    */
    'ignore_patterns' => [
        '*.log',
        '*.cache',
        '.DS_Store',
        'Thumbs.db',
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Polling
    |--------------------------------------------------------------------------
    |
    | Polling configuration (for Docker environments, etc.).
    |
    */
    'polling' => [
        'enabled' => env('SPECTRUM_WATCH_POLL', false),
        'interval' => 1000, // milliseconds
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Server Configuration
    |--------------------------------------------------------------------------
    |
    | Preview server configuration.
    |
    */
    'server' => [
        'host' => 'localhost',
        'port' => 8080,
        'auto_open' => true,
    ],
],

📤 Output Configuration​

/*
|--------------------------------------------------------------------------
| Output Configuration
|--------------------------------------------------------------------------
|
| Output file configuration.
|
*/
'output' => [
    /*
    |--------------------------------------------------------------------------
    | OpenAPI Output
    |--------------------------------------------------------------------------
    |
    | OpenAPI document output location.
    |
    */
    'openapi' => [
        'path' => storage_path('app/spectrum/openapi.json'),
        'format' => 'json', // 'json' or 'yaml'
        'pretty_print' => true,
        'version' => '3.0.0',
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Export Paths
    |--------------------------------------------------------------------------
    |
    | Export file output locations.
    |
    */
    'exports' => [
        'postman' => storage_path('app/spectrum/postman/'),
        'insomnia' => storage_path('app/spectrum/insomnia/'),
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Include Options
    |--------------------------------------------------------------------------
    |
    | Elements to include in output.
    |
    */
    'include' => [
        'examples' => true,
        'descriptions' => true,
        'deprecated' => true,
        'x-properties' => true,
    ],
],

🛡️ Error Handling​

/*
|--------------------------------------------------------------------------
| Error Handling
|--------------------------------------------------------------------------
|
| Error handling configuration.
|
*/
'error_handling' => [
    /*
    |--------------------------------------------------------------------------
    | Fail on Error
    |--------------------------------------------------------------------------
    |
    | Whether to stop processing on error.
    |
    */
    'fail_on_error' => false,
    
    /*
    |--------------------------------------------------------------------------
    | Error Reporting
    |--------------------------------------------------------------------------
    |
    | Error reporting level.
    |
    */
    'reporting' => [
        'level' => 'warning', // 'error', 'warning', 'notice'
        'log_channel' => 'spectrum',
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Error Recovery
    |--------------------------------------------------------------------------
    |
    | Error recovery settings.
    |
    */
    'recovery' => [
        'continue_on_parse_error' => true,
        'use_fallback_types' => true,
        'skip_invalid_routes' => true,
    ],
],

🎯 Advanced Configuration​

/*
|--------------------------------------------------------------------------
| Advanced Configuration
|--------------------------------------------------------------------------
|
| Advanced configuration options.
|
*/
'advanced' => [
    /*
    |--------------------------------------------------------------------------
    | Custom Analyzers
    |--------------------------------------------------------------------------
    |
    | Register custom analyzers.
    |
    */
    'analyzers' => [
        // 'custom' => \App\Spectrum\Analyzers\CustomAnalyzer::class,
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Custom Generators
    |--------------------------------------------------------------------------
    |
    | Register custom generators.
    |
    */
    'generators' => [
        // 'custom' => \App\Spectrum\Generators\CustomGenerator::class,
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Hooks
    |--------------------------------------------------------------------------
    |
    | Hook point configuration.
    |
    */
    'hooks' => [
        'before_analysis' => [],
        'after_analysis' => [],
        'before_generation' => [],
        'after_generation' => [],
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Extensions
    |--------------------------------------------------------------------------
    |
    | OpenAPI extension configuration.
    |
    */
    'extensions' => [
        'x-logo' => [
            'url' => '/logo.png',
            'altText' => 'API Logo',
        ],
        'x-documentation' => 'https://docs.example.com',
    ],
],

💡 Environment Variables​

Key settings can be overridden with environment variables:

# Basic settings
SPECTRUM_USE_FAKER=true
SPECTRUM_FAKER_LOCALE=en_US
SPECTRUM_FAKER_SEED=12345

# Performance
SPECTRUM_WORKERS=8
SPECTRUM_CHUNK_SIZE=100
SPECTRUM_MEMORY_LIMIT=1G

# Cache
SPECTRUM_CACHE_ENABLED=true
SPECTRUM_CACHE_STORE=redis
SPECTRUM_CACHE_TTL=3600

# Watch
SPECTRUM_WATCH_POLL=true

📚 Related Documentation​