Docker＋Laravel＋Swagger UI環境構築

2026/03/24

概要

Docker環境上で、Laravel を用いたAPI開発環境を構築し、Swagger UI によるAPIドキュメント表示まで行う。
構成は以下とする。

  • Webサーバ：Nginx
  • アプリ：Laravel（PHP-FPM）
  • DB：MySQL
  • DB管理：phpMyAdmin
  • APIドキュメント：l5-swagger

Docker環境構築

docker-compose.yml 作成

version: ‘3.8’

services:
app:
build: .
container_name: laravel_app
volumes:
– ./src:/var/www
depends_on:
– db

nginx:
image: nginx:latest
container_name: nginx
ports:
– “8080:80”
volumes:
– ./src:/var/www
– ./nginx/default.conf:/etc/nginx/conf.d/default.conf
depends_on:
– app

db:
image: mysql:8.0
container_name: mysql
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: laravel
ports:
– “3306:3306”

phpmyadmin:
image: phpmyadmin/phpmyadmin
container_name: phpmyadmin
ports:
– “8081:80”
environment:
PMA_HOST: db

Dockerfile 作成（PHP 8系）

FROM php:8.2-fpm

WORKDIR /var/www

RUN apt-get update && apt-get install -y \
git unzip libzip-dev \
&& docker-php-ext-install pdo_mysql zip

COPY –from=composer:latest /usr/bin/composer /usr/bin/composer

コンテナ起動

docker-compose up -d –build

Laravelインストール

docker-compose exec app bash
composer create-project laravel/laravel .

権限エラー対応

以下を実行：

chmod -R 777 storage
chmod -R 777 bootstrap/cache

原因

Laravelは以下に書き込みを行う：

  • storage/
  • bootstrap/cache/

権限が不足しているとエラーになる。

Swagger導入

パッケージインストール

composer require darkaonline/l5-swagger

設定ファイル生成

php artisan vendor:publish –provider=“L5Swagger\L5SwaggerServiceProvider”

Laravel 12 のルーティング注意点

Laravel 12 では
routes/api.php は自動読み込みされない。

対応

bootstrap/app.php に明示的に追加：

->withRouting(
api: __DIR__.’/../routes/api.php’,
)

APIルート作成

routes/api.php

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

Route::get(‘/test’, [TestController::class, ‘index’]);

コントローラ作成

php artisan make:controller Api/TestController

Swagger記述（重要）

今回のポイント。

NG（混在していた状態）

  • @OA\Get（Annotations）
  • #[OA\Get]（Attributes）

→ 混在すると解析されない

OK（Attributesに統一）

<?php

namespace App\Http\Controllers\Api;

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

class TestController extends Controller
{
#[OA\Get(
path: “/api/test”,
summary: “テストAPI”,
responses: [
new OA\Response(
response: 200,
description: “成功”
)
]
)]
public function index()
{
return response()->json([‘message’ => ‘OK’]);
}
}

Swagger生成コマンド

php artisan l5-swagger:generate

役割

  • コードをスキャン
  • OpenAPI(JSON)生成
  • Swagger UI用データ作成

エラーと原因

発生エラー

Required @OA\PathItem() not found

原因

  • AnnotationsとAttributesが混在
  • swagger-phpが正しく解析できない

対応

  • #[ ] に完全統一

Swagger UI確認

ブラウザ：

http://localhost:8080/api/documentation

まとめ

  • DockerでLaravel開発環境構築
  • Swagger導入は l5-swagger を使用
  • Laravel 12はルーティング設定が変更されている
  • Swagger記述は AnnotationsとAttributesを混在させない
  • 今回の詰まりポイントはここ

補足

  • AttributesはPHP8以上必須
  • DockerのPHPバージョンに依存するため注意
← view all