How to Use L5-Swagger for API Documentation in Laravel

What is Swagger?
Swagger (OpenAPI) is a powerful tool for generating interactive API documentation. It helps developers understand and test your API easily.

✅ Step-by-Step Guide to Setup L5-Swagger

1. Install L5-Swagger Package

composer require "darkaonline/l5-swagger"

2. Publish Config & View Files

This command publishes the config file to config/l5-swagger.php:

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

3. Configure Swagger (Optional)

Edit the file config/l5-swagger.php to update:

• API Title
• Base Path
• Directories to scan for annotations

4. Add Swagger Annotations

Add these before your controller class:

/**
* @OA\Info(
*     version="1.0.0",
*     title="Your API Title",
*     description="API documentation for your project",
*     @OA\Contact(
*         email="support@example.com"
*     )
* )
*
* @OA\Server(
*     url=L5_SWAGGER_CONST_HOST,
*     description="API Server"
* )
*/

Annotate methods with routes:

/**
* @OA\Get(
*     path="/api/users",
*     tags={"Users"},
*     summary="Get all users",
*     @OA\Response(
*         response=200,
*         description="Success"
*     )
* )
*/

Import Swagger annotations:

use OpenApi\Annotations as OA;

5. Generate Swagger Docs

php artisan l5-swagger:generate

🛠️ Example: Setting up API Routes & Controller

Create API and Controller

php artisan install:api
php artisan make:controller UserController

Define Routes

// routes/api.php
Route::get('/users', [UserController::class, 'index']);
Route::get('/users/{id}', [UserController::class, 'show']);

UserController with Swagger Annotations

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use OpenApi\Annotations as OA;

/**
* @OA\Info(
*     version="1.0.0",
*     title="Your API Title",
*     description="API documentation for your project",
*     @OA\Contact(
*         email="support@example.com"
*     )
* )
*
* @OA\Server(
*     url=L5_SWAGGER_CONST_HOST,
*     description="API Server"
* )
*/
class UserController extends Controller
{
    /**
    * @OA\Get(
    *     path="/api/users",
    *     tags={"Users"},
    *     summary="Get all users",
    *     @OA\Response(
    *         response=200,
    *         description="Success"
    *     )
    * )
    */
    public function index(Request $request) {
        return User::all();
    }

    /**
    * @OA\Get(
    *     path="/api/users/{id}",
    *     tags={"Users"},
    *     summary="Get User by ID",
    *     @OA\Parameter(
    *         name="id",
    *         in="path",
    *         required=true,
    *         description="ID of the user",
    *         @OA\Schema(type="integer")
    *     ),
    *     @OA\Response(
    *         response=200,
    *         description="Success"
    *     ),
    *     @OA\Response(
    *         response=404,
    *         description="User not found"
    *     )
    * )
    */
    public function show(Request $request, $id) {
        return User::find($id);
    }
}

🚀 Final Result

Visit /api/documentation in your Laravel app to see the interactive Swagger UI with all your documented endpoints.

🎯 Why Use L5-Swagger?

• Auto-generates interactive API docs.
• Improves API collaboration between frontend & backend teams.
• Makes testing APIs easier with a user-friendly UI.

🔗 GitHub Project

You can find the full source code for this integration on GitHub:
👉 github.com/RanaGithub30/laravel-swagger-example