設定リファレンス

config/spectrum.phpファイルの全設定項目の詳細なリファレンスです。

📋 設定ファイルの公開

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

🔧 基本設定

API情報

/*
|--------------------------------------------------------------------------
| API Documentation Title
|--------------------------------------------------------------------------
|
| APIドキュメントのタイトル。ドキュメントの上部に表示されます。
|
*/
'title' => env('APP_NAME', 'Laravel') . ' API',

/*
|--------------------------------------------------------------------------
| API Version
|--------------------------------------------------------------------------
|
| APIのバージョン。OpenAPI仕様に含まれます。
|
*/
'version' => '1.0.0',

/*
|--------------------------------------------------------------------------
| API Description
|--------------------------------------------------------------------------
|
| APIの説明文。Markdown形式で記述可能です。
|
*/
'description' => 'API documentation generated by Laravel Spectrum',

/*
|--------------------------------------------------------------------------
| Terms of Service URL
|--------------------------------------------------------------------------
|
| 利用規約のURL（オプション）。
|
*/
'terms_of_service' => 'https://example.com/terms',

/*
|--------------------------------------------------------------------------
| Contact Information
|--------------------------------------------------------------------------
|
| API提供者の連絡先情報。
|
*/
'contact' => [
    'name' => 'API Support',
    'email' => 'api@example.com',
    'url' => 'https://example.com/support',
],

/*
|--------------------------------------------------------------------------
| License Information
|--------------------------------------------------------------------------
|
| APIのライセンス情報。
|
*/
'license' => [
    'name' => 'MIT',
    'url' => 'https://opensource.org/licenses/MIT',
],

OpenAPI仕様バージョン

/*
|--------------------------------------------------------------------------
| OpenAPI Specification Version
|--------------------------------------------------------------------------
|
| 生成するOpenAPI仕様のバージョン。
| 対応バージョン: '3.0.0', '3.1.0'
|
| OpenAPI 3.1.0の特徴:
| - JSON Schema Draft 2020-12との完全互換
| - nullable キーワードの代わりに型配列を使用（例: ["string", "null"]）
| - Webhooksサポート
|
*/
'openapi' => [
    'version' => env('SPECTRUM_OPENAPI_VERSION', '3.0.0'),
],

サーバー設定

/*
|--------------------------------------------------------------------------
| Servers
|--------------------------------------------------------------------------
|
| APIサーバーのリスト。複数の環境を定義できます。
|
*/
'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 Patterns
|--------------------------------------------------------------------------
|
| ドキュメントに含めるルートのパターン。ワイルドカード（*）を使用できます。
|
*/
'route_patterns' => [
    'api/*',
    'api/v1/*',
    'api/v2/*',
],

/*
|--------------------------------------------------------------------------
| Custom Route Files
|--------------------------------------------------------------------------
|
| 標準のLaravelルートファイル以外に解析対象とする追加のルートファイル。
|
*/
'route_files' => [
    // base_path('routes/custom.php'),
    // base_path('routes/admin.php'),
],

🏷️ タグ設定

/*
|--------------------------------------------------------------------------
| Tag Mappings
|--------------------------------------------------------------------------
|
| ルートをグループ化するためのタグマッピング。
| 完全一致またはワイルドカード（*）を使用できます。
|
*/
'tags' => [
    // 完全一致
    // 'api/v1/auth/login' => 'Authentication',

    // ワイルドカード
    // 'api/v1/auth/*' => 'Authentication',
    // 'api/v1/admin/*' => 'Administration',
],

/*
|--------------------------------------------------------------------------
| Tag Groups (x-tagGroups)
|--------------------------------------------------------------------------
|
| タグをグループ化してドキュメントビューアー（Redoc等）で
| より整理された表示にします。
|
*/
'tag_groups' => [
    // 'User Management' => ['User', 'Profile', 'Auth'],
    // 'Content' => ['Post', 'Comment', 'Media'],
    // 'Administration' => ['Admin', 'Settings'],
],

/*
|--------------------------------------------------------------------------
| Tag Descriptions
|--------------------------------------------------------------------------
|
| 各タグの説明。OpenAPIのtagsセクションに反映されます。
|
*/
'tag_descriptions' => [
    // 'User' => 'ユーザー管理と認証エンドポイント',
    // 'Post' => 'ブログ投稿のCRUD操作',
],

/*
|--------------------------------------------------------------------------
| Ungrouped Tags Group Name
|--------------------------------------------------------------------------
|
| グループに割り当てられていないタグを配置するグループ名。
| nullに設定すると、未グループのタグはx-tagGroupsに表示されません。
|
*/
'ungrouped_tags_group' => 'Other',

🔐 認証設定

/*
|--------------------------------------------------------------------------
| Authentication Configuration
|--------------------------------------------------------------------------
|
| APIの認証方式の設定。
|
*/
'authentication' => [
    /*
    |--------------------------------------------------------------------------
    | Global Authentication
    |--------------------------------------------------------------------------
    |
    | すべてのエンドポイントに適用するグローバル認証設定。
    |
    */
    'global' => [
        'enabled' => false,
        'scheme' => [
            'type' => 'http',
            'scheme' => 'bearer',
            'bearerFormat' => 'JWT',
            'description' => 'グローバルJWT認証',
            'name' => 'globalAuth',
        ],
        'required' => false,
    ],

    /*
    |--------------------------------------------------------------------------
    | Custom Authentication Schemes
    |--------------------------------------------------------------------------
    |
    | ミドルウェア名をOpenAPIセキュリティスキームにマッピング。
    |
    */
    'custom_schemes' => [
        // 'custom-auth' => [
        //     'type' => 'apiKey',
        //     'in' => 'header',
        //     'name' => 'X-Custom-Token',
        //     'description' => 'カスタムAPIトークン',
        // ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Pattern-based Authentication
    |--------------------------------------------------------------------------
    |
    | パターンマッチングによるルートへの認証適用。
    |
    */
    'patterns' => [
        // 'api/admin/*' => [
        //     'scheme' => [...],
        //     'required' => true,
        // ],
    ],

    /*
    |--------------------------------------------------------------------------
    | OAuth2 Configuration (for Passport)
    |--------------------------------------------------------------------------
    |
    | Laravel Passport用のOAuth2設定。
    |
    */
    'oauth2' => [
        'authorization_url' => env('APP_URL') . '/oauth/authorize',
        'token_url' => env('APP_URL') . '/oauth/token',
        'refresh_url' => env('APP_URL') . '/oauth/token',
        'scopes' => [
            // 'read' => '読み取りアクセス',
            // 'write' => '書き込みアクセス',
        ],
    ],
],

🎨 例データ生成

/*
|--------------------------------------------------------------------------
| Example Generation
|--------------------------------------------------------------------------
|
| リクエスト/レスポンス例の生成設定。
|
*/
'example_generation' => [
    /*
    |--------------------------------------------------------------------------
    | Use Faker
    |--------------------------------------------------------------------------
    |
    | Fakerを使用してリアルな例データを生成するか。
    |
    */
    'use_faker' => env('SPECTRUM_USE_FAKER', true),
    
    /*
    |--------------------------------------------------------------------------
    | Faker Locale
    |--------------------------------------------------------------------------
    |
    | Fakerのロケール設定。
    |
    */
    'faker_locale' => env('SPECTRUM_FAKER_LOCALE', 'ja_JP'),
    
    /*
    |--------------------------------------------------------------------------
    | Faker Seed
    |--------------------------------------------------------------------------
    |
    | 一貫した例データを生成するためのシード値。
    |
    */
    'faker_seed' => env('SPECTRUM_FAKER_SEED', null),
    
    /*
    |--------------------------------------------------------------------------
    | Custom Field Generators
    |--------------------------------------------------------------------------
    |
    | 特定のフィールド名に対するカスタムジェネレーター。
    |
    */
    '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
    |--------------------------------------------------------------------------
    |
    | 配列の例で生成する要素数。
    |
    */
    'array_limits' => [
        'min' => 1,
        'max' => 3,
    ],
],

⚡ パフォーマンス設定

/*
|--------------------------------------------------------------------------
| Performance Configuration
|--------------------------------------------------------------------------
|
| パフォーマンス最適化の設定。
|
*/
'performance' => [
    'enabled' => env('SPECTRUM_PERFORMANCE_ENABLED', true),

    // 並列処理
    'parallel_processing' => env('SPECTRUM_PARALLEL_PROCESSING', true),
    'max_workers' => env('SPECTRUM_MAX_WORKERS', null), // null = 自動検出

    // チャンク処理
    'chunk_size' => env('SPECTRUM_CHUNK_SIZE', 100),
    'auto_chunk_size' => true, // 最適なチャンクサイズを自動計算

    // メモリ管理
    'memory_limit' => env('SPECTRUM_MEMORY_LIMIT', '512M'),
    'memory_warning_threshold' => 0.8, // 80%
    'memory_critical_threshold' => 0.9, // 90%

    // インクリメンタル生成
    'incremental' => [
        'enabled' => env('SPECTRUM_INCREMENTAL_ENABLED', true),
        'track_dependencies' => true,
        'cache_dependencies' => true,
    ],

    // プロファイリング
    'profiling' => [
        'enabled' => env('SPECTRUM_PROFILING_ENABLED', false),
        'save_reports' => true,
        'report_path' => storage_path('spectrum/profiling'),
    ],
],

💾 キャッシュ設定

/*
|--------------------------------------------------------------------------
| Cache Configuration
|--------------------------------------------------------------------------
|
| キャッシュの設定。
|
*/
'cache' => [
    // キャッシュを有効にするか
    'enabled' => env('SPECTRUM_CACHE_ENABLED', true),

    // キャッシュディレクトリ
    'directory' => storage_path('app/spectrum/cache'),

    // キャッシュの有効期限（秒）。nullで無期限
    'ttl' => env('SPECTRUM_CACHE_TTL', null),

    // 変更を監視してキャッシュを無効化するファイル
    'watch_files' => [
        base_path('composer.json'),
        base_path('composer.lock'),
    ],
],

👁️ Watch設定

/*
|--------------------------------------------------------------------------
| Watch Configuration
|--------------------------------------------------------------------------
|
| ファイル監視の設定。
|
*/
'watch' => [
    // 監視するディレクトリ
    'paths' => [
        app_path('Http/Controllers'),
        app_path('Http/Requests'),
        app_path('Http/Resources'),
        base_path('routes'),
    ],

    // 無視するパターン
    'ignore' => [
        '*.log',
        '*.cache',
        '.git',
        'vendor',
        'node_modules',
    ],

    // 複数ファイル保存時の待機時間（ミリ秒）
    'debounce' => 300,
],

✅ バリデーション設定

/*
|--------------------------------------------------------------------------
| Validation Analysis
|--------------------------------------------------------------------------
|
| バリデーションルールの検出と解析設定。
|
*/
'validation' => [
    'analyze_inline' => true,       // インラインバリデーションを解析
    'analyze_form_requests' => true, // FormRequestを解析
],

🔄 トランスフォーマー設定

/*
|--------------------------------------------------------------------------
| Response Transformer Support
|--------------------------------------------------------------------------
|
| 各種レスポンス変換ライブラリのサポート設定。
|
*/
'transformers' => [
    'enabled' => [
        'laravel-resource' => true,
        'fractal' => true,
    ],

    'fractal' => [
        'default_serializer' => 'array', // array, data_array, json_api
        'include_handling' => 'optional_properties',
        'pagination_schema' => [...], // ページネーションスキーマ
    ],
],

🔍 レスポンス検出設定

/*
|--------------------------------------------------------------------------
| Response Detection Configuration
|--------------------------------------------------------------------------
|
| コントローラーメソッドからのレスポンスボディ自動検出設定。
|
*/
'response_detection' => [
    'enabled' => env('SPECTRUM_RESPONSE_DETECTION', true),
    'include_model_attributes' => true,
    'max_depth' => 3,
    'type_inference' => [
        'strict' => false,
        'fallback_type' => 'string',
    ],
    'cache_model_schemas' => true,
],

🌐 HTML出力設定

/*
|--------------------------------------------------------------------------
| HTML Output Settings
|--------------------------------------------------------------------------
|
| Swagger UIを使用したHTML出力設定。
|
*/
'html' => [
    'try_it_out' => env('SPECTRUM_HTML_TRY_IT_OUT', true),
    'persist_authorization' => true,
    'deep_linking' => true,
    'doc_expansion' => 'list', // list, full, none
    'filter' => true,
],

📤 エクスポート設定

/*
|--------------------------------------------------------------------------
| Export Settings
|--------------------------------------------------------------------------
|
| PostmanやInsomniaへのエクスポート設定。
|
*/
'export' => [
    'postman' => [
        'include_examples' => true,
        'include_tests' => true,
        'include_pre_request_scripts' => true,
        'group_by_tags' => true,
    ],

    'insomnia' => [
        'include_examples' => true,
        'include_environments' => true,
        'default_timeout' => 30000,
    ],

    'environment_variables' => [
        // 'custom_header' => 'X-Custom-Header',
    ],

    'auth_presets' => [
        'bearer' => [
            'type' => 'bearer',
            'token_placeholder' => '{{bearer_token}}',
        ],
        'api_key' => [
            'type' => 'apikey',
            'key_placeholder' => '{{api_key}}',
            'header' => 'X-API-Key',
        ],
    ],
],

🎭 モックサーバー設定

/*
|--------------------------------------------------------------------------
| Mock Server Settings
|--------------------------------------------------------------------------
|
| モックAPIサーバーの設定。
|
*/
'mock_server' => [
    'default_host' => '127.0.0.1',
    'default_port' => 8081,

    'response' => [
        'delay' => env('SPECTRUM_MOCK_DELAY', 0),
        'scenarios' => [
            'success' => 'Successful response',
            'error' => 'Server error (500)',
            'not_found' => 'Resource not found (404)',
            'forbidden' => 'Access forbidden (403)',
            'validation_error' => 'Validation failed (422)',
        ],
        'random_error_rate' => env('SPECTRUM_MOCK_ERROR_RATE', 0),
    ],

    'auth' => [
        'valid_tokens' => [
            'test-token-123',
            'Bearer test-jwt-token',
        ],
        'public_paths' => [
            'POST /api/auth/login',
            'POST /api/auth/register',
            'GET /api/health',
        ],
    ],

    'faker' => [
        'locale' => config('app.faker_locale', 'en_US'),
        'seed' => env('SPECTRUM_MOCK_SEED', null),
    ],
],

🛡️ エラーハンドリング

/*
|--------------------------------------------------------------------------
| Error Handling
|--------------------------------------------------------------------------
|
| エラーハンドリングの設定。
|
*/
'error_handling' => [
    'fail_on_error' => env('SPECTRUM_FAIL_ON_ERROR', false),
    'error_report_path' => storage_path('app/spectrum/error-report.json'),
    'ignore_patterns' => [
        // '/vendor/' // vendorディレクトリのエラーを無視
    ],
    'notifications' => [
        'enabled' => false,
        'channels' => ['log'],
    ],
],

💡 環境変数

主要な設定は環境変数でオーバーライドできます：

# OpenAPI
SPECTRUM_OPENAPI_VERSION=3.0.0

# 例データ生成
SPECTRUM_USE_FAKER=true
SPECTRUM_FAKER_LOCALE=ja_JP
SPECTRUM_FAKER_SEED=12345

# パフォーマンス
SPECTRUM_PERFORMANCE_ENABLED=true
SPECTRUM_PARALLEL_PROCESSING=true
SPECTRUM_MAX_WORKERS=8
SPECTRUM_CHUNK_SIZE=100
SPECTRUM_MEMORY_LIMIT=1G
SPECTRUM_INCREMENTAL_ENABLED=true

# キャッシュ
SPECTRUM_CACHE_ENABLED=true
SPECTRUM_CACHE_TTL=3600

# レスポンス検出
SPECTRUM_RESPONSE_DETECTION=true

# HTML出力
SPECTRUM_HTML_TRY_IT_OUT=true

# エラーハンドリング
SPECTRUM_FAIL_ON_ERROR=false

# モックサーバー
SPECTRUM_MOCK_DELAY=0
SPECTRUM_MOCK_ERROR_RATE=0
SPECTRUM_MOCK_SEED=12345

📚 関連ドキュメント

インストールと設定 - 初期設定ガイド
パフォーマンス最適化 - パフォーマンス設定の詳細
カスタマイズ - 高度なカスタマイズ

📋 設定ファイルの公開​

🔧 基本設定​

API情報​

OpenAPI仕様バージョン​

サーバー設定​

📂 ルート設定​

🏷️ タグ設定​

🔐 認証設定​

🎨 例データ生成​

⚡ パフォーマンス設定​

💾 キャッシュ設定​

👁️ Watch設定​

✅ バリデーション設定​

🔄 トランスフォーマー設定​

🔍 レスポンス検出設定​

🌐 HTML出力設定​

📤 エクスポート設定​

🎭 モックサーバー設定​

🛡️ エラーハンドリング​

💡 環境変数​

📚 関連ドキュメント​

📋 設定ファイルの公開

🔧 基本設定

API情報

OpenAPI仕様バージョン

サーバー設定

📂 ルート設定

🏷️ タグ設定

🔐 認証設定

🎨 例データ生成

⚡ パフォーマンス設定

💾 キャッシュ設定

👁️ Watch設定

✅ バリデーション設定

🔄 トランスフォーマー設定

🔍 レスポンス検出設定

🌐 HTML出力設定

📤 エクスポート設定

🎭 モックサーバー設定

🛡️ エラーハンドリング

💡 環境変数

📚 関連ドキュメント