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',
],

OpenAPI Specification Version​

/*
|--------------------------------------------------------------------------
| OpenAPI Specification Version
|--------------------------------------------------------------------------
|
| The OpenAPI specification version to use for generating documentation.
| Supported versions: '3.0.0', '3.1.0'
|
| OpenAPI 3.1.0 includes:
| - Full JSON Schema Draft 2020-12 compatibility
| - Type arrays instead of nullable keyword (e.g., ["string", "null"])
| - Webhooks support
|
*/
'openapi' => [
    'version' => env('SPECTRUM_OPENAPI_VERSION', '3.0.0'),
],

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/*',
],

/*
|--------------------------------------------------------------------------
| Custom Route Files
|--------------------------------------------------------------------------
|
| Additional route files to analyze beyond the standard Laravel route files.
|
*/
'route_files' => [
    // base_path('routes/custom.php'),
    // base_path('routes/admin.php'),
],

🏷️ Tag Configuration​

/*
|--------------------------------------------------------------------------
| Tag Mappings
|--------------------------------------------------------------------------
|
| Tag mappings for grouping routes.
| You can use exact matches or wildcards (*).
|
*/
'tags' => [
    // Exact match
    // 'api/v1/auth/login' => 'Authentication',

    // Wildcard
    // 'api/v1/auth/*' => 'Authentication',
    // 'api/v1/admin/*' => 'Administration',
],

/*
|--------------------------------------------------------------------------
| Tag Groups (x-tagGroups)
|--------------------------------------------------------------------------
|
| Group tags for better organization in documentation viewers
| that support x-tagGroups extension (e.g., Redoc).
|
*/
'tag_groups' => [
    // 'User Management' => ['User', 'Profile', 'Auth'],
    // 'Content' => ['Post', 'Comment', 'Media'],
    // 'Administration' => ['Admin', 'Settings'],
],

/*
|--------------------------------------------------------------------------
| Tag Descriptions
|--------------------------------------------------------------------------
|
| Descriptions for each tag, reflected in the OpenAPI tags section.
|
*/
'tag_descriptions' => [
    // 'User' => 'User management and authentication endpoints',
    // 'Post' => 'Blog post CRUD operations',
],

/*
|--------------------------------------------------------------------------
| Ungrouped Tags Group Name
|--------------------------------------------------------------------------
|
| Name of the group for tags not assigned to any group.
| Set to null to hide ungrouped tags from x-tagGroups.
|
*/
'ungrouped_tags_group' => 'Other',

🔐 Authentication Configuration​

/*
|--------------------------------------------------------------------------
| Authentication Configuration
|--------------------------------------------------------------------------
|
| Configuration for API authentication methods.
|
*/
'authentication' => [
    /*
    |--------------------------------------------------------------------------
    | Global Authentication
    |--------------------------------------------------------------------------
    |
    | Global authentication settings applied to all endpoints.
    | Set 'enabled' to true to apply this security scheme to all endpoints.
    |
    */
    'global' => [
        'enabled' => false,
        'scheme' => [
            'type' => 'http',
            'scheme' => 'bearer',
            'bearerFormat' => 'JWT',
            'description' => 'Global JWT authentication',
            'name' => 'globalAuth',
        ],
        'required' => false,
    ],

    /*
    |--------------------------------------------------------------------------
    | Custom Authentication Schemes
    |--------------------------------------------------------------------------
    |
    | Define custom authentication schemes for use in the generated documentation.
    | Map middleware names to OpenAPI security schemes.
    |
    */
    'custom_schemes' => [
        // 'custom-auth' => [
        //     'type' => 'apiKey',
        //     'in' => 'header',
        //     'name' => 'X-Custom-Token',
        //     'description' => 'Custom API token',
        // ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Authentication Patterns
    |--------------------------------------------------------------------------
    |
    | Route patterns that require specific authentication.
    | Use wildcards (*) for pattern matching.
    |
    */
    'patterns' => [
        // 'api/admin/*' => 'adminAuth',
        // 'api/v1/*' => 'bearerAuth',
    ],

    /*
    |--------------------------------------------------------------------------
    | OAuth2 Configuration
    |--------------------------------------------------------------------------
    |
    | OAuth2-specific configuration.
    |
    */
    'oauth2' => [
        'flows' => [
            'authorizationCode' => [
                'authorizationUrl' => '/oauth/authorize',
                'tokenUrl' => '/oauth/token',
                'refreshUrl' => '/oauth/token/refresh',
                'scopes' => [
                    'read' => 'Read permission',
                    'write' => 'Write permission',
                    'delete' => 'Delete permission',
                ],
            ],
        ],
    ],
],

🎨 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' => [
    /*
    |--------------------------------------------------------------------------
    | Parallel Processing
    |--------------------------------------------------------------------------
    |
    | Enable parallel processing for large codebases.
    | Requires spatie/fork package.
    |
    */
    'parallel' => env('SPECTRUM_PARALLEL', false),

    /*
    |--------------------------------------------------------------------------
    | Worker Count
    |--------------------------------------------------------------------------
    |
    | Number of workers for parallel processing.
    | 'auto' uses the number of CPU cores.
    |
    */
    'workers' => env('SPECTRUM_WORKERS', 'auto'),

    /*
    |--------------------------------------------------------------------------
    | Memory Limit
    |--------------------------------------------------------------------------
    |
    | Memory limit for each worker.
    |
    */
    'memory_limit' => env('SPECTRUM_MEMORY_LIMIT', '512M'),
],

💾 Cache Configuration​

/*
|--------------------------------------------------------------------------
| Cache Configuration
|--------------------------------------------------------------------------
|
| Cache settings for analysis results.
|
*/
'cache' => [
    /*
    |--------------------------------------------------------------------------
    | Enable Cache
    |--------------------------------------------------------------------------
    |
    | Whether to enable caching of analysis results.
    |
    */
    'enabled' => env('SPECTRUM_CACHE_ENABLED', true),

    /*
    |--------------------------------------------------------------------------
    | Cache Directory
    |--------------------------------------------------------------------------
    |
    | Directory for storing cache files.
    |
    */
    'directory' => storage_path('app/spectrum/cache'),

    /*
    |--------------------------------------------------------------------------
    | Cache TTL
    |--------------------------------------------------------------------------
    |
    | Cache expiration time in seconds. null for indefinite.
    |
    */
    'ttl' => env('SPECTRUM_CACHE_TTL', null),
],

👁️ Watch Configuration​

/*
|--------------------------------------------------------------------------
| Watch Configuration
|--------------------------------------------------------------------------
|
| File watching configuration for spectrum:watch command.
|
*/
'watch' => [
    /*
    |--------------------------------------------------------------------------
    | Watch Paths
    |--------------------------------------------------------------------------
    |
    | Directories and files to watch for changes.
    |
    */
    'paths' => [
        app_path('Http/Controllers'),
        app_path('Http/Requests'),
        app_path('Http/Resources'),
        base_path('routes'),
        config_path(),
    ],

    /*
    |--------------------------------------------------------------------------
    | Ignore Patterns
    |--------------------------------------------------------------------------
    |
    | File patterns to ignore during file watching.
    |
    */
    'ignore_patterns' => [
        '*.log',
        '*.cache',
        '.DS_Store',
        'Thumbs.db',
    ],
],

✅ Validation Configuration​

/*
|--------------------------------------------------------------------------
| Validation Configuration
|--------------------------------------------------------------------------
|
| Configuration for validation rule analysis.
|
*/
'validation' => [
    /*
    |--------------------------------------------------------------------------
    | Strict Mode
    |--------------------------------------------------------------------------
    |
    | In strict mode, unrecognized validation rules cause warnings.
    |
    */
    'strict_mode' => false,
],

🔄 Transformers Configuration​

/*
|--------------------------------------------------------------------------
| Transformers Configuration
|--------------------------------------------------------------------------
|
| Custom type transformers for schema generation.
|
*/
'transformers' => [
    // \App\Spectrum\Transformers\CustomTransformer::class,
],

📡 Response Detection Configuration​

/*
|--------------------------------------------------------------------------
| Response Detection Configuration
|--------------------------------------------------------------------------
|
| Configuration for automatic response detection.
|
*/
'response_detection' => [
    /*
    |--------------------------------------------------------------------------
    | Enable Response Detection
    |--------------------------------------------------------------------------
    |
    | Whether to enable automatic response type detection.
    |
    */
    'enabled' => true,

    /*
    |--------------------------------------------------------------------------
    | Analyze Method Body
    |--------------------------------------------------------------------------
    |
    | Whether to analyze method bodies for return statements.
    |
    */
    'analyze_method_body' => true,
],

🌐 HTML Output Configuration​

/*
|--------------------------------------------------------------------------
| HTML Output Configuration
|--------------------------------------------------------------------------
|
| Configuration for HTML output with Swagger UI.
|
*/
'html' => [
    /*
    |--------------------------------------------------------------------------
    | Theme
    |--------------------------------------------------------------------------
    |
    | Swagger UI theme. Options: 'default', 'dark'
    |
    */
    'theme' => 'default',

    /*
    |--------------------------------------------------------------------------
    | Try It Out
    |--------------------------------------------------------------------------
    |
    | Whether to enable the "Try It Out" feature.
    |
    */
    'try_it_out' => true,
],

📤 Export Configuration​

/*
|--------------------------------------------------------------------------
| Export Configuration
|--------------------------------------------------------------------------
|
| Configuration for Postman and Insomnia exports.
|
*/
'export' => [
    /*
    |--------------------------------------------------------------------------
    | Postman Export
    |--------------------------------------------------------------------------
    |
    | Postman export configuration.
    |
    */
    'postman' => [
        'output_path' => storage_path('app/spectrum/postman'),
        'environments' => [
            'local' => [
                'base_url' => env('APP_URL', 'http://localhost'),
            ],
            'staging' => [
                'base_url' => 'https://staging.example.com',
            ],
            'production' => [
                'base_url' => 'https://api.example.com',
            ],
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Insomnia Export
    |--------------------------------------------------------------------------
    |
    | Insomnia export configuration.
    |
    */
    'insomnia' => [
        'output_path' => storage_path('app/spectrum/insomnia/insomnia_collection.json'),
    ],
],

🎭 Mock Server Configuration​

/*
|--------------------------------------------------------------------------
| Mock Server Configuration
|--------------------------------------------------------------------------
|
| Configuration for the mock API server.
|
*/
'mock_server' => [
    /*
    |--------------------------------------------------------------------------
    | Default Host
    |--------------------------------------------------------------------------
    |
    | Default host address to bind the server.
    |
    */
    'host' => env('SPECTRUM_MOCK_HOST', '127.0.0.1'),

    /*
    |--------------------------------------------------------------------------
    | Default Port
    |--------------------------------------------------------------------------
    |
    | Default port number for the server.
    |
    */
    'port' => env('SPECTRUM_MOCK_PORT', 8081),

    /*
    |--------------------------------------------------------------------------
    | Response Delay
    |--------------------------------------------------------------------------
    |
    | Default response delay in milliseconds.
    |
    */
    'delay' => env('SPECTRUM_MOCK_DELAY', 0),

    /*
    |--------------------------------------------------------------------------
    | Default Scenario
    |--------------------------------------------------------------------------
    |
    | Default response scenario ('success' or 'error').
    |
    */
    'scenario' => 'success',
],

🛡️ Error Handling​

/*
|--------------------------------------------------------------------------
| Error Handling Configuration
|--------------------------------------------------------------------------
|
| Error handling configuration.
|
*/
'error_handling' => [
    /*
    |--------------------------------------------------------------------------
    | Fail on Error
    |--------------------------------------------------------------------------
    |
    | Whether to stop processing when an error is encountered.
    |
    */
    'fail_on_error' => false,

    /*
    |--------------------------------------------------------------------------
    | Ignore Errors
    |--------------------------------------------------------------------------
    |
    | Whether to ignore errors and continue processing.
    |
    */
    'ignore_errors' => false,
],

💡 Environment Variables​

Key settings can be overridden with environment variables:

# OpenAPI
SPECTRUM_OPENAPI_VERSION=3.0.0    # or 3.1.0

# Example Generation
SPECTRUM_USE_FAKER=true
SPECTRUM_FAKER_LOCALE=en_US
SPECTRUM_FAKER_SEED=12345

# Performance
SPECTRUM_PARALLEL=true
SPECTRUM_WORKERS=8
SPECTRUM_MEMORY_LIMIT=1G

# Cache
SPECTRUM_CACHE_ENABLED=true
SPECTRUM_CACHE_TTL=3600

# Mock Server
SPECTRUM_MOCK_HOST=127.0.0.1
SPECTRUM_MOCK_PORT=8081
SPECTRUM_MOCK_DELAY=0

📚 Related Documentation​