Laravel + Swaggerで API設計書を自動生成！5ステップ導入

October 19, 2025

LaravelでAPIを開発していて、「API設計書を手動でメンテナンスするのが面倒」「フロントエンドとバックエンドで仕様の認識がズレる」といった課題に直面していませんか？Swagger（OpenAPI）を導入すれば、コードからAPI設計書を自動生成できます。

この記事では、LaravelプロジェクトにSwaggerを導入して、API設計書を自動生成する手順を5つのステップで解説します。実際に動作するコード例を使って、すぐに実装できる内容になっています。

Swagger（OpenAPI）とは？

SwaggerはAPI設計のためのツールセットで、OpenAPIという統一仕様に基づいてAPIドキュメントを生成できます。厳密に言うと、OpenAPIが仕様、Swaggerがそのツールやフレームワークということになります。

Swaggerのメリット

一貫性のあるAPI設計：チーム全体で同じドキュメントを参照できる
開発の並行作業：バックエンド開発を待たずにフロントエンド開発を進められる
自動生成：コードから設計書が自動生成されるため、ドキュメントとコードの乖離を防げる
インタラクティブなテスト：ブラウザ上で直接APIをテストできる

Swaggerのデメリット

学習コスト：アノテーション記法を覚える必要がある
複雑な構造の表現：ネストした配列や複雑なオブジェクトの定義が難しい場合がある

ただし、メリットの方が圧倒的に大きいため、チーム開発では導入する価値が十分にあります。

導入手順（5ステップ）

それでは実際に、LaravelプロジェクトにSwaggerを導入していきましょう。

前提条件

Laravel 11がインストール済み
Composerが使える環境
基本的なLaravel開発環境が整っている

Step 1: Swagger-phpのインストール

まず、Swagger生成ライブラリのswagger-phpをComposerでインストールします。

composer require zircote/swagger-php

Laravel Sailを使っている場合は、以下のコマンドです。

./vendor/bin/sail composer require zircote/swagger-php

Step 2: l5-swaggerのインストールと設定

次に、LaravelでSwaggerドキュメントを生成・表示するためのl5-swaggerパッケージをインストールします。

composer require "darkaonline/l5-swagger"
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

2つ目のコマンドで設定ファイルがconfig/l5-swagger.phpにパブリッシュされます。

Step 3: 基本設定の記述

app/Http/Controllers/Controller.phpに、API全体の基本情報を記述します。

<?php

namespace App\Http\Controllers;
use OpenApi\Attributes as OA;

/**
 * @OA\Info(
 *     version="1.0.0",
 *     title="Sample API Document",
 *     description="Sample API Document for Laravel + Swagger"
 * )
 *
 * @OA\Server(
 *     url="http://localhost/api",
 *     description="Local Development Server"
 * )
 */
abstract class Controller
{
    //
}

この設定で、APIのバージョン、タイトル、説明、サーバーURLを定義できます。

Step 4: APIエンドポイントの定義

サンプルのコントローラーを作成して、APIエンドポイントを定義します。

php artisan make:controller SampleController --api

作成されたapp/Http/Controllers/SampleController.phpにアノテーションを追加します。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class SampleController extends Controller
{
    /**
     * @OA\Get(
     *     path="/sample",
     *     summary="サンプル一覧取得",
     *     description="サンプルデータの一覧を取得します",
     *     tags={"Sample"},
     *     @OA\Response(
     *         response=200,
     *         description="成功"
     *     )
     * )
     */
    public function index()
    {
        return response()->json(['message' => 'Sample Index']);
    }

    /**
     * @OA\Post(
     *     path="/sample",
     *     summary="サンプル作成",
     *     description="新しいサンプルデータを作成します",
     *     tags={"Sample"},
     *     @OA\RequestBody(
     *         required=true,
     *         @OA\JsonContent(
     *             required={"name"},
     *             @OA\Property(property="name", type="string", example="サンプル名"),
     *             @OA\Property(property="description", type="string", example="説明文")
     *         )
     *     ),
     *     @OA\Response(
     *         response=201,
     *         description="作成成功"
     *     )
     * )
     */
    public function store(Request $request)
    {
        return response()->json(['message' => 'Sample Created'], 201);
    }
}

この例では、GETメソッド（一覧取得）とPOSTメソッド（作成）の2つのエンドポイントを定義しています。POSTの方では、リクエストBodyの構造も定義しているのがポイントです。

Step 5: ドキュメント生成と確認

最後に、Swaggerドキュメントを生成します。

php artisan l5-swagger:generate

生成が完了したら、ブラウザで以下のURLにアクセスしてください。

http://localhost/api/documentation

すると、美しいSwagger UIでAPI設計書が表示されます。各エンドポイントをクリックすれば、詳細な仕様が確認でき、ブラウザから直接APIをテストすることもできます。

実践例：レスポンスBodyの詳細定義

より実践的な例として、レスポンスBodyの構造も定義してみましょう。

/**
 * @OA\Get(
 *     path="/sample/{id}",
 *     summary="サンプル詳細取得",
 *     tags={"Sample"},
 *     @OA\Parameter(
 *         name="id",
 *         in="path",
 *         required=true,
 *         description="サンプルID",
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="成功",
 *         @OA\JsonContent(
 *             @OA\Property(property="id", type="integer", example=1),
 *             @OA\Property(property="name", type="string", example="サンプル名"),
 *             @OA\Property(property="description", type="string", example="説明文"),
 *             @OA\Property(property="created_at", type="string", format="date-time", example="2024-01-01T00:00:00Z")
 *         )
 *     ),
 *     @OA\Response(
 *         response=404,
 *         description="見つかりません"
 *     )
 * )
 */
public function show($id)
{
    return response()->json([
        'id' => $id,
        'name' => 'サンプル名',
        'description' => '説明文',
        'created_at' => now()
    ]);
}

この例では、パスパラメータ、成功レスポンス（200）、エラーレスポンス（404）をすべて定義しています。これにより、フロントエンド開発者が正確なレスポンス構造を把握できます。

よくあるトラブルと解決法

トラブル1: ドキュメントが生成されない

原因：アノテーションの構文エラー、または設定ファイルのパスが間違っている。

解決法：

config/l5-swagger.phpのpaths.annotationsが正しいか確認
アノテーションの閉じタグ（*/）が正しく記述されているか確認
エラーログを確認：storage/logs/laravel.log

トラブル2: 404エラーでドキュメントページが表示されない

原因：ルーティングが正しく設定されていない。

解決法：

# キャッシュをクリア
php artisan route:clear
php artisan config:clear

# ルートリストを確認
php artisan route:list | grep swagger

トラブル3: 複雑なデータ構造が定義できない

原因：ネストした配列やオブジェクトの表現方法が分からない。

解決法：@OA\Schemaを使って独立したスキーマを定義し、それを参照する方法がおすすめです。

/**
 * @OA\Schema(
 *     schema="User",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="name", type="string"),
 *     @OA\Property(
 *         property="posts",
 *         type="array",
 *         @OA\Items(ref="#/components/schemas/Post")
 *     )
 * )
 */

まとめ：Swaggerで開発効率を大幅アップ

Laravel + Swaggerの導入により、API設計書の自動生成とチーム間の認識統一が実現できます。最初の学習コストはありますが、一度覚えてしまえば開発効率が劇的に向上します。

導入のポイントまとめ：

swagger-phpとl5-swaggerをインストール
Controller.phpに基本設定を記述
各コントローラーメソッドにアノテーションで定義
php artisan l5-swagger:generateでドキュメント生成
ブラウザで/api/documentationにアクセス

まずは簡単なGET/POSTエンドポイントから始めて、徐々に複雑な定義に挑戦していきましょう。フロントエンドとバックエンドの連携がスムーズになり、開発のボトルネックが大幅に解消されるはずです。

Laravel開発をさらに効率化する関連記事

Swagger導入でAPI開発を効率化したら、他の開発ツールやAI支援ツールも活用して、さらに生産性を向上させましょう：

開発効率化・コーディング支援

opencode – ターミナル向けAIコーディングエージェント！複数モデル対応で柔軟な開発支援を実現 – ターミナルから直接AIを活用してコーディング効率を大幅向上
Qoder – AIが完全理解するソフトウェア開発向け次世代IDE – プロジェクト全体を理解するAI搭載IDEで開発体験を革新
Byterover – AI開発者向け自己改善型コーディング知識管理プラットフォーム – コーディングパターンを蓄積してチーム全体の開発品質を向上

API開発・連携

Perplexity Search API – 高精度な検索インフラを提供する開発者向けAPI – 強力な検索機能をアプリに統合してユーザー体験を向上
CREAO – AIを活用したカスタムアプリ開発プラットフォーム – 自然言語でアプリケーションを構築して開発を加速
Cipher by Byterover – AIコーディング支援のための共有メモリー管理プラットフォーム – コーディング履歴を自動記録してプロジェクト間で知識共有

Laravel + Swagger よくある質問

❓ Swagger（OpenAPI）とは何ですか？

SwaggerはAPI設計のためのツールセットで、OpenAPIという統一された仕様に基づいています。厳密には、OpenAPIが仕様、Swaggerがそのツール群という関係です。Laravel開発では、コードにアノテーションを記述することで、自動的にAPIドキュメントを生成できます。手動でドキュメントを書く手間が省け、コードとドキュメントの乖離も防げます。

❓ l5-swaggerとswagger-phpの違いは何ですか？

swagger-phpはPHPコードからSwagger/OpenAPI仕様書を生成するライブラリです。l5-swaggerは、このswagger-phpをLaravelで使いやすくするためのパッケージで、ドキュメント生成コマンドやSwagger UIの表示機能を提供します。両方をインストールすることで、Laravelプロジェクトで簡単にSwaggerドキュメントを生成・表示できます。

❓ アノテーションの書き方が難しいのですが、参考資料はありますか？

公式ドキュメントが最も信頼できる情報源です。swagger-phpの公式GitHubリポジトリ（https://github.com/zircote/swagger-php）には豊富なサンプルがあります。また、OpenAPI Specification（https://swagger.io/specification/）を参照すると、各アノテーションの意味を深く理解できます。複雑な構造は、まず簡単な例から始めて徐々に拡張していくのがおすすめです。

❓ 本番環境でもSwagger UIを公開すべきですか？

セキュリティの観点から、本番環境では公開しないことを推奨します。config/l5-swagger.phpで環境ごとに設定を変更でき、本番環境ではSwagger UIへのアクセスを無効化できます。開発環境やステージング環境でのみ有効にし、本番環境ではBasic認証やIP制限をかけるか、完全に無効化するのが一般的です。社内向けAPIの場合は、認証付きで公開する選択肢もあります。

よかったらシェアしてね！

URLをコピーしました！

URLをコピーしました！