Laravel 11でAPIプロジェクトを作成・設定する方法

2026年6月21日

Contents

1 Laravel 11 プロジェクトの作成と基本設定
- 1.1 プロジェクト作成とキー・データベース設定
- 1.2 まとめ
2 API ルートファイルとミドルウェアグループの仕組み
3 実践的なルーティング：シンプル定義から apiResource まで
4 API の高度化：バージョニング・認証・モデルバインディング
5 デプロイ・テスト・トラブルシューティング

スポンサードリンク

Laravel 11 プロジェクトの作成と基本設定

Laravel 11 を API 開発に利用する際は、まず開発環境を正しく構築しておくことが成功の鍵です。このセクションでは Composer でのインストール手順 と .env の最低限の設定項目 を具体的に示します。これらが完了すれば、すぐにルーティングやコントローラの実装へと移行できます。

プロジェクト作成とキー・データベース設定

# Laravel 11 の新規プロジェクトを作成（バージョン 11 系統を指定）
composer create-project laravel/laravel my-api &quot;11.*&quot;

cd my-api

# アプリケーションキーの自動生成
php artisan key:generate

# Laravel 11 の新規プロジェクトを作成（バージョン 11 系統を指定）

composer create-project laravel/laravel my-api "11.*"

cd my-api

# アプリケーションキーの自動生成

php artisan key:generate

続いて .env にアプリ名・環境情報・データベース接続情報を記入します。以下はローカル開発用の例です。

cat &gt;&gt; .env &lt;&lt;EOF
APP_NAME=MyAPI
APP_ENV=local
APP_KEY=$(php -r &quot;echo 'base64:' . base64_encode(random_bytes(32));&quot;)
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=my_api_db
DB_USERNAME=root
DB_PASSWORD=
EOF

cat >> .env <<EOF

APP_NAME=MyAPI

APP_ENV=local

APP_KEY=$(php -r "echo 'base64:' . base64_encode(random_bytes(32));")

APP_DEBUG=true

APP_URL=http://localhost

DB_CONNECTION=mysql

DB_HOST=127.0.0.1

DB_PORT=3306

DB_DATABASE=my_api_db

DB_USERNAME=root

DB_PASSWORD=

EOF

ポイント
- php artisan key:generate が生成したキーは .env の APP_KEY に自動で書き込まれますが、上記のように手動で設定しても問題ありません。
- データベース情報は実際に使用する環境（MySQL、PostgreSQL 等）に合わせて調整してください。

まとめ

以上の手順だけで Laravel 11 の開発基盤が完成します。次は API 用ルートファイルとミドルウェアグループ の関係を確認し、実装へ進めましょう。

API ルートファイルとミドルウェアグループの仕組み

Laravel 11 のデフォルトスケルトンには routes/api.php が 自動的に生成 されます（Laravel 10 以前から変わりません）。このファイルは RouteServiceProvider によって読み込まれ、api ミドルウェアグループが自動で付与されるため、開発者が個別に web ミドルウェアを意識する必要はありません。

`routes/api.php` の役割と自動適用ミドルウェア

RouteServiceProvider::mapApiRoutes() が内部で次のように定義されています（Laravel 11 のデフォルト実装）。

protected function mapApiRoutes()
{
    Route::prefix('api')
        -&gt;middleware('api')   // ← ここで api ミドルウェアスタックが付与される
        -&gt;group(base_path('routes/api.php'));
}

protected function mapApiRoutes()

{

Route::prefix('api')

->middleware('api') // ← ここで api ミドルウェアスタックが付与される

->group(base_path('routes/api.php'));

}

この設定により、routes/api.php に記述した全てのルートは throttle:api・bindings・substituteBindings など を含む api ミドルウェアスタックが自動的に適用されます。したがって、ファイル内で改めて Route::middleware('api') と書く必要は基本的にはありません。

`api.php` に明示的にミドルウェアを付与するケース

以下のような特殊な要件がある場合にだけ、個別でミドルウェアを上書きしたり追加したりします。

ルート単位で 認証ガード（例：auth:sanctum）や カスタムレートリミット を設定したいとき
api グループ以外のミドルウェア（例：cors）を追加したいとき

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\HealthCheckController;

// 認証が不要なヘルスチェックは個別に middleware を省略できる
Route::get('/health', [HealthCheckController::class, 'show'])
     -&gt;withoutMiddleware(['auth:sanctum']);

use Illuminate\Support\Facades\Route;

use App\Http\Controllers\Api\HealthCheckController;

// 認証が不要なヘルスチェックは個別に middleware を省略できる

Route::get('/health', [HealthCheckController::class, 'show'])

->withoutMiddleware(['auth:sanctum']);

まとめ

routes/api.php はデフォルトで生成され、api ミドルウェアグループが自動付与されます。
基本的にファイル内で Route::middleware('api') を書く必要はありませんが、認証やカスタムミドルウェアを個別に指定したい場合は明示できます。

実践的なルーティング：シンプル定義から `apiResource` まで

このセクションでは、最小構成のエンドポイント と CRUD 用の自動生成ルート の両方を具体例とともに紹介します。まずは手軽に動作確認できるクロージャベースの実装から始め、続いて本格的なコントローラ駆動のパターンへ移ります。

基本的な GET / POST エンドポイント

routes/api.php に次のコードを追記すれば、簡単な ping エンドポイントとリクエスト内容をそのまま返す echo エンドポイントが完成します。先ほど説明した通り、api ミドルウェアは自動で適用されます。

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('/ping', function () {
    return response()-&gt;json(['message' =&gt; 'pong']);
});

Route::post('/echo', function (Request $request) {
    return response()-&gt;json($request-&gt;all());
});

use Illuminate\Http\Request;

use Illuminate\Support\Facades\Route;

Route::get('/ping', function () {

return response()->json(['message' => 'pong']);

});

Route::post('/echo', function (Request $request) {

return response()->json($request->all());

});

ポイント
- Route::get と Route::post はクロージャでもコントローラメソッドでも同様に使用できます。
- テストやデバッグ時はクロージャが手軽で、実装後はコントローラへリファクタリングすると保守性が向上します。

`apiResource` を使った CRUD ルートの一括生成

RESTful な API の典型例として ユーザー管理 を考えます。Laravel 11 では Route::apiResource が自動的に index, store, show, update, destroy の5つのアクションを作成します。

コントローラを API 用テンプレートで生成（--api オプションはリソースコレクション系メソッドを除外）

bash php artisan make:controller Api/UserController --api

routes/api.php にルート定義を追加

php use App\Http\Controllers\Api\UserController;

Route::apiResource('users', UserController::class);

生成されたルートは次のようになります（php artisan route:list --path=api/users で確認可能）

メソッド	URI	アクション
GET	/api/users	index
POST	/api/users	store
GET	/api/users/{user}	show
PUT/PATCH	/api/users/{user}	update
DELETE	/api/users/{user}	destroy

注意点
- apiResource は自動的に api ミドルウェアを使用しますので、別途ラップする必要はありません。
- コントローラメソッドでは型ヒントでモデルバインディングが機能し、余計な Route::model 設定は不要です。

まとめ

クロージャだけでも数行で GET/POST エンドポイントを実装でき、開発初期の検証に最適です。
本格的な CRUD は apiResource と API 用コントローラの組み合わせがベストプラクティスとなります。

API の高度化：バージョニング・認証・モデルバインディング

実務で求められる API には バージョン管理、認証保護、そして 型安全なモデルバインディング が欠かせません。ここではそれぞれの実装例とベストプラクティスを示します。

バージョニング（`v1`, `v2` …）

Route::prefix と名前空間の組み合わせでシンプルにバージョン分けができます。Laravel 11 では自動的に PSR‑4 に従うため、コントローラの配置だけで名前空間が解決されます。

use App\Http\Controllers\Api\V1\UserController;
use App\Http\Controllers\Api\V2\UserController as UserV2Controller;

Route::prefix('v1')
    -&gt;group(function () {
        Route::apiResource('users', UserController::class);
    });

Route::prefix('v2')
    -&gt;group(function () {
        // v2 では追加カラムやロジックが変更されたコントローラを使用
        Route::apiResource('users', UserV2Controller::class);
    });

use App\Http\Controllers\Api\V1\UserController;

use App\Http\Controllers\Api\V2\UserController as UserV2Controller;

Route::prefix('v1')

->group(function () {

Route::apiResource('users', UserController::class);

});

Route::prefix('v2')

->group(function () {

// v2 では追加カラムやロジックが変更されたコントローラを使用

Route::apiResource('users', UserV2Controller::class);

});

ベネフィット
- エンドポイントは https://example.com/api/v1/users、/api/v2/users と明確に分離でき、将来的な互換性維持が容易です。

認証ミドルウェアの適用例

Laravel 11 が標準で提供する Sanctum はシンプルなトークン認証を実装できます。以下は Sanctum を使った保護ルートのサンプルです。

use Illuminate\Http\Request;
use App\Http\Controllers\Api\AuthController;

Route::post('/login', [AuthController::class, 'login']);

Route::middleware('auth:sanctum')
    -&gt;group(function () {
        Route::get('/profile', function (Request $request) {
            return $request-&gt;user();
        });

        // 既存の CRUD ルートも同じグループに入れられる
        Route::apiResource('posts', App\Http\Controllers\Api\PostController::class);
    });

use Illuminate\Http\Request;

use App\Http\Controllers\Api\AuthController;

Route::post('/login', [AuthController::class, 'login']);

Route::middleware('auth:sanctum')

->group(function () {

Route::get('/profile', function (Request $request) {

return $request->user();

});

// 既存の CRUD ルートも同じグループに入れられる

Route::apiResource('posts', App\Http\Controllers\Api\PostController::class);

});

Passport を利用した OAuth2 認証や、サードパーティ製 JWT パッケージ（tymon/jwt-auth）でも同様に auth:passport やカスタムミドルウェア名を指定すれば OK です。

改良されたモデルバインディング

Laravel 11 では 暗黙的バインディング が高速化され、明示的な Route::model 呼び出しは不要になりました。コントローラのメソッドで型ヒントを付けるだけです。

namespace App\Http\Controllers\Api\V1;

use App\Models\User;
use Illuminate\Http\JsonResponse;

class UserController extends Controller
{
    public function show(User $user): JsonResponse
    {
        return response()-&gt;json($user);
    }

    public function update(User $user, Request $request): JsonResponse
    {
        $user-&gt;update($request-&gt;validated());
        return response()-&gt;json($user);
    }
}

namespace App\Http\Controllers\Api\V1;

use App\Models\User;

use Illuminate\Http\JsonResponse;

class UserController extends Controller

{

public function show(User $user): JsonResponse

{

return response()->json($user);

}

public function update(User $user, Request $request): JsonResponse

{

$user->update($request->validated());

return response()->json($user);

}

ポイント
- ルートパラメータ名（{user}）がモデルの単数形と一致すれば、Laravel が自動で検索・インジェクトします。
- カスタムキー（例：UUID）を使う場合は public function getRouteKeyName(): string { return 'uuid'; } をモデルに実装してください。

まとめ

バージョニングは prefix と名前空間でシンプルに実装できます。
認証は Sanctum がデフォルトで最も手軽ですが、要件に応じて Passport や JWT へ切り替え可能です。
モデルバインディングは型ヒントだけで完結し、コードが格段に読みやすくなります。

デプロイ・テスト・トラブルシューティング

本番環境で安定稼働させるための キャッシュ管理 と 自動テスト のベストプラクティスをまとめます。特に routes/api.php が存在しない状態で実行するとエラーになるケースについても対処法を示します。

ルーティングキャッシュの使い方と注意点

# 本番デプロイ直前の推奨コマンド
php artisan config:cache      # 設定ファイルをキャッシュ
php artisan route:cache       # ルート情報をキャッシュ
php artisan view:cache        # ビューコンパイル結果をキャッシュ

# 本番デプロイ直前の推奨コマンド

php artisan config:cache # 設定ファイルをキャッシュ

php artisan route:cache # ルート情報をキャッシュ

php artisan view:cache # ビューコンパイル結果をキャッシュ

必須条件：routes/api.php がプロジェクト内に存在し、正しい PHP 構文で記述されていること。
キャッシュが古い場合は php artisan route:clear で削除し、再度 route:cache を実行してください。

PHPUnit と Pest による API テスト例

PHPUnit（`tests/Feature/UserApiTest.php`）

&lt;?php

namespace Tests\Feature;

use Tests\TestCase;
use App\Models\User;
use Laravel\Sanctum\Sanctum;

class UserApiTest extends TestCase
{
    /** @test */
    public function it_returns_user_list()
    {
        // 認証が必要な場合は Sanctum で擬似ユーザーを作成
        Sanctum::actingAs(User::factory()-&gt;create());

        $response = $this-&gt;getJson('/api/v1/users');

        $response-&gt;assertOk()
                 -&gt;assertJsonStructure(['data']);
    }
}

<?php

namespace Tests\Feature;

use Tests\TestCase;

use App\Models\User;

use Laravel\Sanctum\Sanctum;

class UserApiTest extends TestCase

{

/** @test */

public function it_returns_user_list()

{

// 認証が必要な場合は Sanctum で擬似ユーザーを作成

Sanctum::actingAs(User::factory()->create());

$response = $this->getJson('/api/v1/users');

$response->assertOk()

->assertJsonStructure(['data']);

}

Pest（`tests/Feature/UserApiTest.php`）

it('gets user list', function () {
    // 認証が必要なら Sanctum::actingAs() を呼び出す
    getJson('/api/v1/users')
        -&gt;assertOk()
        -&gt;assertJsonPath('data', fn ($d) =&gt; expect($d)-&gt;toBeArray());
});

it('gets user list', function () {

// 認証が必要なら Sanctum::actingAs() を呼び出す

getJson('/api/v1/users')

->assertOk()

->assertJsonPath('data', fn ($d) => expect($d)->toBeArray());

});

ベストプラクティス
- テスト実行前に必ず php artisan route:clear を CI のセットアップ段階で走らせ、キャッシュによる影響を排除します。

`routes/api.php がない` エラーへの対処法

手動作成
プロジェクトの routes ディレクトリに以下の最小構成ファイルを作ります。

php ['message' => 'pong']);

2. **RouteServiceProvider の確認**
app/Providers/RouteServiceProvider.php にある mapApiRoutes() がコメントアウトされていないかチェックします。デフォルトは次の通りです。

php protected function mapApiRoutes() { Route::prefix('api') ->middleware('api') ->group(base_path('routes/api.php')); }

3. **キャッシュクリア**
ルートファイルを追加・修正した後は必ず php artisan route:clear を実行し、再度 route:cache（必要なら）を行ってください。

### まとめ

* routes/api.php はデフォルトで生成され、api ミドルウェアが自動付与されます。
* キャッシュは本番環境のパフォーマンス向上に有効ですが、ファイル欠損時にはエラーになるため事前確認が必須です。
* テストはキャッシュの影響を排除した状態で実行し、認証が必要な場合は Sanctum 等で擬似ユーザーを作成するとスムーズです。

---

## 全体まとめ

Laravel 11 で API 開発を始める際に最も重要なのは **正しいプロジェクト構築** と **ルート・ミドルウェアの理解** です。本稿では以下のポイントを網羅しました。

1. Composer による Laravel 11 のインストールと .env 設定
2. routes/api.php がデフォルトで生成され、api ミドルウェアが自動付与される仕組み
3. シンプルな GET/POST エンドポイントから apiResource による CRUD の一括生成までの流れ
4. バージョニング・認証（Sanctum 等）・暗黙的モデルバインディングの実装例
5. ルーティングキャッシュ、テスト、そして「ファイルがない」エラーへの対処法

これらを踏まえてプロジェクトをセットアップすれば、**ステートレスかつ高速な API** を即座に構築できるはずです。実装後は必ずテストとキャッシュのクリア・再生成を行い、本番環境へ安全にデプロイしてください。 Happy coding!

スポンサードリンク

-Laravel

comment コメントをキャンセル

: Laravel

Railway無料プラン2026:Laravelデプロイ制限と手順

2023年以降のRailway無料プラン変更内容とLaravelデプロイ手順を解説。リソース制限やDBアドオンコスト、Renderなど代替サービス比較も掲載。

Electron vs Tauri: 2026年の実用比較

Jetpack Compose 入門 2025年最新バージョン

Laravel 11でAPIプロジェクトを作成・設定する方法

Laravel 11 プロジェクトの作成と基本設定

プロジェクト作成とキー・データベース設定

まとめ

API ルートファイルとミドルウェアグループの仕組み

routes/api.php の役割と自動適用ミドルウェア

api.php に明示的にミドルウェアを付与するケース

まとめ

実践的なルーティング：シンプル定義から apiResource まで

基本的な GET / POST エンドポイント

apiResource を使った CRUD ルートの一括生成

まとめ

API の高度化：バージョニング・認証・モデルバインディング

バージョニング（v1, v2 …）

認証ミドルウェアの適用例

改良されたモデルバインディング

まとめ

デプロイ・テスト・トラブルシューティング

ルーティングキャッシュの使い方と注意点

PHPUnit と Pest による API テスト例

PHPUnit（tests/Feature/UserApiTest.php）

Pest（tests/Feature/UserApiTest.php）

routes/api.php がない エラーへの対処法

Laravel 11でAPIプロジェクトを作成・設定する方法

Laravel 11 プロジェクトの作成と基本設定

`routes/api.php` の役割と自動適用ミドルウェア

`api.php` に明示的にミドルウェアを付与するケース

実践的なルーティング：シンプル定義から `apiResource` まで

`apiResource` を使った CRUD ルートの一括生成

バージョニング（`v1`, `v2` …）

PHPUnit（`tests/Feature/UserApiTest.php`）

Pest（`tests/Feature/UserApiTest.php`）

`routes/api.php がない` エラーへの対処法