インストールと設定

このガイドでは、Laravel Spectrumのインストールから初期設定までを詳しく説明します。

📋 要件

• PHP 8.1以上
• Laravel 10.x、11.x、12.x
• Composer 2.0以上

🚀 インストール

Laravel 11のセットアップ

Laravel 11では、APIルートがまだ存在しない場合は、最初にインストールする必要があります：

php artisan install:api

このコマンドは以下を実行します：

• Laravel Sanctumをインストール
• routes/api.phpファイルを作成
• API認証を設定

Composerでインストール

composer require wadakatu/laravel-spectrum --dev

Laravelの自動検出

Laravel 5.5以降では、サービスプロバイダーは自動的に登録されます。

⚙️ 設定ファイルの公開

デフォルト設定をカスタマイズする場合は、設定ファイルを公開します：

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

これにより、config/spectrum.phpファイルが作成されます。

🔧 基本設定

APIの基本情報

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

ルートパターン

ドキュメントに含めるルートのパターンを指定します：

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

除外ルート

特定のルートをドキュメントから除外する場合：

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

🔐 認証設定

Bearer Token（JWT/Sanctum）

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

API Key認証

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

🎨 カスタマイズ

タグの設定

エンドポイントを整理するためのタグマッピング：

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

レスポンス例のカスタマイズ

'example_generation' => [
    'use_faker' => true,
    'faker_locale' => 'ja_JP',
    'faker_seed' => 12345, // 一貫した例データを生成
    'custom_generators' => [
        'status' => fn($faker) => $faker->randomElement(['active', 'inactive']),
        'role' => fn($faker) => $faker->randomElement(['admin', 'user']),
    ],
],

📁 出力設定

出力先の変更

'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' => [
    'enabled' => true,
    'ttl' => 3600, // 1時間
    'directory' => storage_path('app/spectrum/cache'),
],

⚠️ 重要な注意事項

コントローラーベースのルートのみサポート

Laravel Spectrumはコントローラーベースのルートのみをサポートしています。クロージャルートはサポートされていません：

// ❌ サポートされない - クロージャルート
Route::get('/api/test', function () {
    return ['message' => 'test'];
});

// ✅ サポートされる - コントローラールート
Route::get('/api/test', [TestController::class, 'index']);

クロージャルートをコントローラールートに変換する方法：

1. コントローラーを作成: php artisan make:controller Api/TestController
2. クロージャのロジックをコントローラーメソッドに移動
3. ルートをコントローラーを使用するように更新

設定ファイル

設定ファイルが自動的に公開されない場合は、手動でコピーしてください：

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

ルートパターンマッチング

ルートパターンでワイルドカードを正しく使用してください：

'route_patterns' => [
    'api/*',     // api/users、api/postsにマッチ
    'api/**',    // ネストされたパス用（すべてのバージョンで動作しない場合があります）
    'api/v1/*',  // api/v1/users、api/v1/postsにマッチ
],

🚨 トラブルシューティング

権限エラー

ストレージディレクトリへの書き込み権限を確認：

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

ルートが検出されない

1. route:cacheをクリアする：

   php artisan route:clear

2. ルートパターンが正しいか確認：

   // config/spectrum.php
   'route_patterns' => [
       'api/*', // すべてのAPIルート
   ],

📚 次のステップ

• 基本的な使い方 - ドキュメントの生成方法
• 機能一覧 - 利用可能な全機能
• 設定リファレンス - 詳細な設定オプション