Laravel

Swagger in Laravel: Step-by-Step Guide with Example

Introduction

Swagger is a powerful API documentation tool that simplifies learning and testing different endpoints. With the darkaonline/l5-swagger package, integrating Swagger into Laravel is straightforward, enabling developers to create interactive API documentation with ease. This guide provides a step-by-step process to set up Swagger in your Laravel project, complete with an example to get you started.

Step 1: Install Swagger Package

First, install the Swagger package using Composer:

composer require darkaonline/l5-swagger

This command adds the darkaonline/l5-swagger package to your Laravel project, which acts as a wrapper for swagger-php and swagger-ui, tailored for Laravel.

Step 2: Publish Configuration

Run the following command to publish the Swagger configuration file:

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

This command creates a `config/l5-swagger.php` file in your project, allowing you to customize Swagger settings.

Step 3: Configure Swagger

Open the `config/l5-swagger.php` file and update necessary settings, such as API title, version, or base URL, under the `api` section. For dynamic base URLs, you can set the `L5_SWAGGER_CONST_HOST` variable in your `.env` file, e.g.:

L5_SWAGGER_CONST_HOST=http://your-app-url/api/v1

Optionally, enable automatic documentation generation in development by setting `L5_SWAGGER_GENERATE_ALWAYS=true` in your `.env` file (not recommended for production).

Step 4: Add Swagger Annotations to Routes

Swagger uses annotations to generate API documentation. Add annotations to your controller methods to describe your API endpoints. Here’s an example:

namespace App\Http\Controllers;use Illuminate\Http\Request;/*** @OA\Get(* path="/api/example",* summary="Get Example Data",* @OA\Response(response=200, description="Success"),* )*/class ExampleController extends Controller{public function getData(){return response()->json(['message' => 'Swagger Implemented']);}}

This annotation describes a GET endpoint at `/api/example` that returns a JSON response. For more complex annotations, refer to the swagger-php documentation.

Step 5: Create API Documentation

Generate the Swagger documentation by running:

php artisan l5-swagger:generate

This command scans your annotated controllers and generates a JSON file, which is then rendered as an interactive HTML page via Swagger UI.

Step 6: Access Swagger UI

Start your Laravel application with:

php artisan serve

Then, open your browser and navigate to:

http://your-app-url/api/documentation

You’ll see an interactive Swagger UI where you can explore and test your API endpoints.

Conclusion

Swagger makes API documentation effortless in Laravel. With the darkaonline/l5-swagger package, you can generate interactive API docs in just a few steps, enhancing development and testing. By following this guide, you can quickly set up Swagger, customize it to your needs, and create a user-friendly interface for your API consumers. Happy coding!

Ready to transform your business with our technology solutions? Contact Us today to Leverage Our Laravel Expertise.