Laravel Swagger Integration: Step-by-Step Guide to Generate API Documentation

kavita.laravel311

24 July 2026

Introduction

Laravel Swagger Integration is one of the best ways to generate interactive API documentation for your Laravel applications.

When building REST APIs with Laravel, maintaining accurate and up-to-date documentation is essential for developers and API consumers.

Use Swagger (OpenAPI) with the L5-Swagger package to automatically generate and maintain your API documentation.

In this tutorial, Learn to integrate L5-Swagger with Laravel, configure authentication, document APIs, and generate Swagger UI.

Prerequisites

Before starting, make sure you have:

Laravel project installed
PHP 8.1 or higher
Composer installed
MySQL or another supported database
Basic knowledge of Laravel APIs

Step 1: Install Packages for Laravel Swagger Integration

First, install the Swagger package along with JWT Authentication.

composer require darkaonline/l5-swagger tymon/jwt-auth

1	composer require darkaonline/l5-swagger tymon/jwt-auth

What these packages do

darkaonline/l5-swagger generates OpenAPI documentation.
tymon/jwt-auth enables JWT authentication for protected APIs.

Step 2: Configure JWT Authentication

Publish the JWT configuration file.

php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

1	php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

Laravel creates a new configuration file:

config/jwt.php

1	config/jwt.php

Next, generate the JWT secret key.

php artisan jwt:secret

1	php artisan jwt:secret

This command automatically updates your .env file with a JWT secret.

Step 3: Publish Laravel Swagger Configuration

Now publish the L5-Swagger configuration.

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

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

After publishing, Laravel creates:

config/l5-swagger.php

1	config/l5-swagger.php

This configuration file allows you to customize:

Documentation URL
Scan directories
API information
Security settings
Swagger UI options

Step 4: Create the User Registration API

Create a controller if it doesn’t already exist.

php artisan make:controller UserController

1	php artisan make:controller UserController

Inside the controller, create a register() method.

Add Swagger annotations above the method.

/**
 * @OA\Post(
 *     path="/api/register",
 *     summary="Register User",
 *     tags={"Authentication"},
 *     @OA\Response(
 *         response=201,
 *         description="User registered successfully"
 *     )
 * )
 */

/**

* @OA\Post(

* path="/api/register",

* summary="Register User",

* tags={"Authentication"},

* @OA\Response(

* response=201,

* description="User registered successfully"

* )

The method should:

Validate user input
Create a new user
Hash the password
Return a success response

Once Swagger scans this annotation, the endpoint automatically appears in the documentation.

Step 5: Create Login Controller

Generate a login controller.

php artisan make:controller LoginController

1	php artisan make:controller LoginController

This controller will authenticate users and return a JWT token after successful login.

Step 6: Implement Login API

Document the login endpoint.

/**
 * @OA\Post(
 *     path="/api/login",
 *     summary="User Login",
 *     tags={"Authentication"},
 *     @OA\Response(
 *         response=200,
 *         description="Login Successful"
 *     )
 * )
 */

/**

* @OA\Post(

* path="/api/login",

* summary="User Login",

* tags={"Authentication"},

* @OA\Response(

* response=200,

* description="Login Successful"

* )

Inside the login method:

Validate credentials
Authenticate the user
Generate a token
Return the token in JSON format

Example response:

{
    "token":"your_access_token"
}

{

"token":"your_access_token"

}

Step 7: Create Protected User Endpoint

Add another method to return authenticated user details.

/**
 * @OA\Get(
 *     path="/api/user",
 *     summary="Get Logged-in User",
 *     tags={"User"},
 *     security={{"bearerAuth":{}}},
 *     @OA\Response(
 *         response=200,
 *         description="Success"
 *     )
 * )
 */

/**

* @OA\Get(

* path="/api/user",

* summary="Get Logged-in User",

* tags={"User"},

* security={{"bearerAuth":{}}},

* @OA\Response(

* response=200,

* description="Success"

* )

This endpoint requires a valid Bearer Token.

When users authorize in Swagger UI, they can directly test this API.

Step 8: Register API Routes

Open:

routes/api.php

1 2	routes/api.php

Route::post('/register',[UserController::class,'register']); 

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

Route::middleware('auth:sanctum')->get('/user',[UserController::class,'getUserDetails']);

Route::post('/register',[UserController::class,'register']);

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

Route::middleware('auth:sanctum')->get('/user',[UserController::class,'getUserDetails']);

Note: Choose one authentication system (JWT or Sanctum) and configure your middleware consistently.

Step 9: Configure Swagger Information

Open your base controller or create a dedicated annotations file.

Add global API information.

/**
 * @OA\Info(
 *     title="Laravel Swagger API",
 *     version="1.0.0",
 *     description="API Documentation"
 * )
 *
 * @OA\SecurityScheme(
 *     securityScheme="bearerAuth",
 *     type="http",
 *     scheme="bearer",
 *     bearerFormat="JWT"
 * )
 */

/**

* @OA\Info(

* title="Laravel Swagger API",

* version="1.0.0",

* description="API Documentation"

* )

* @OA\SecurityScheme(

* securityScheme="bearerAuth",

* type="http",

* scheme="bearer",

* bearerFormat="JWT"

* )

This information appears at the top of Swagger UI.

Step 10: Generate Laravel Swagger Documentation

Generate the documentation by running:

php artisan l5-swagger:generate

1	php artisan l5-swagger:generate

The package scans your controllers for OpenAPI annotations and generates the API documentation automatically.

Step 11: View Swagger UI

Start your Laravel server.

php artisan serve

1	php artisan serve

Now open the following URL:

http://127.0.0.1:8000/api/documentation

1 2	http://127.0.0.1:8000/api/documentation

You will see an interactive Swagger dashboard containing:

All API endpoints
Request parameters
Response schemas
Authentication options
“Try it out” feature

You can even test APIs directly from the browser without using Postman.

Testing Protected APIs

For authenticated routes:

Login using the /login endpoint.
Copy the returned Bearer Token.
Click the Authorize button in Swagger UI.
Enter:

Bearer YOUR_ACCESS_TOKEN

1 2	Bearer YOUR_ACCESS_TOKEN

Click Authorize.
You can now access protected endpoints directly from Swagger.

Common Commands

Install packages:

composer require darkaonline/l5-swagger tymon/jwt-auth

1	composer require darkaonline/l5-swagger tymon/jwt-auth

Publish Swagger config:

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

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

Publish JWT config:

php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

1	php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

Generate JWT secret:

php artisan jwt:secret

1	php artisan jwt:secret

Generate Swagger documentation:

php artisan l5-swagger:generate

1	php artisan l5-swagger:generate

Run the application:

php artisan serve

1	php artisan serve

Conclusion

Integrating Swagger into Laravel makes API documentation simple, interactive, and always up to date.

L5-Swagger documents API endpoints using OpenAPI annotations. It also generates interactive API docs and lets you test APIs from Swagger UI.

This approach reduces manual documentation effort and improves collaboration across development teams.

Also you can hire laravel developers to customize this feature for your business needs.
Kindly explore our extensions.