DEV Community

Sospeter Mong'are
Sospeter Mong'are

Posted on

1

How to Generate and Display Swagger (OpenAPI) Documentation for Your Laravel API

Swagger, now known as OpenAPI, is a powerful tool to describe your API's endpoints, request parameters, responses, and more in a standardized format. It helps both frontend developers and external users understand how to interact with your API.

In this article, we'll walk through the process of integrating Swagger/OpenAPI documentation into a Laravel API using the l5-swagger package.

Step 1: Install the l5-swagger Package

To get started with Swagger documentation in your Laravel application, you first need to install the l5-swagger package. This package makes it easy to generate and display OpenAPI documentation.

Run the following command to install l5-swagger via Composer:

composer require darkaonline/l5-swagger
Enter fullscreen mode Exit fullscreen mode

Step 2: Publish the Configuration File

After installing the package, publish the configuration file for l5-swagger. This allows you to customize the settings for the Swagger UI and the OpenAPI documentation.

Use this command:

php artisan vendor:publish --provider="L5Swagger\L5SwaggerServiceProvider"
Enter fullscreen mode Exit fullscreen mode

This will create the config/l5-swagger.php configuration file, where you can tweak the settings for Swagger.

Step 3: Set Up OpenAPI Annotations

OpenAPI documentation is built using annotations in the code. These annotations describe your API’s endpoints, input parameters, output responses, and more.

The primary annotation is @OA\Info, which contains the metadata about your API, such as its title, version, and description.

Where to Place OpenAPI Annotations

You can place OpenAPI annotations in the following locations:

  • Controller: Directly within the controller that defines your routes.
  • Separate Documentation Class: A dedicated file or class that contains all of your OpenAPI annotations.

Example: Adding @OA\Info in a Controller

Here's how you can add @OA\Info in a controller. For this example, we will add it to an ApiController:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

/**
 * @OA\Info(
 *     title="HookBox API",
 *     version="1.0.0",
 *     description="This is the API documentation for the HookBox API. It handles webhook requests and responses, allowing users to generate and display data dynamically."
 * )
 */
class ApiController extends Controller
{
    // Your controller methods here
}
Enter fullscreen mode Exit fullscreen mode

Example: Adding @OA\Info in a Separate Documentation Class

If you want to keep your OpenAPI metadata separate from your controllers, you can create a new class specifically for OpenAPI annotations.

Create a file like app/Swagger/ApiDocumentation.php:

<?php

namespace App\Swagger;

/**
 * @OA\Info(
 *     title="HookBox API",
 *     version="1.0.0",
 *     description="This is the API documentation for the HookBox API. It handles webhook requests and responses, allowing users to generate and display data dynamically."
 * )
 */
class ApiDocumentation
{
    // Other Swagger-related annotations if needed
}
Enter fullscreen mode Exit fullscreen mode

Other Useful OpenAPI Annotations

Here are some other useful annotations you can add in your controllers or routes:

  • @OA\PathItem: Defines the API paths.
  • @OA\Operation: Describes individual operations (endpoints) for your API.
  • @OA\Parameter: Describes input parameters for your endpoints.
  • @OA\Response: Describes the response structure for an endpoint.

Example of defining an endpoint with annotations:

/**
 * @OA\Get(
 *     path="/api/endpoint",
 *     summary="Fetch data",
 *     @OA\Response(
 *         response=200,
 *         description="Success",
 *         @OA\JsonContent(
 *             type="object",
 *             @OA\Property(property="data", type="string", example="Sample data")
 *         )
 *     )
 * )
 */
public function getData()
{
    return response()->json(['data' => 'Sample data']);
}
Enter fullscreen mode Exit fullscreen mode

Step 4: Generate Swagger Documentation

After you've added the annotations in your code, it's time to generate the Swagger documentation.

Run the following artisan command:

php artisan l5-swagger:generate
Enter fullscreen mode Exit fullscreen mode

This command will scan your controllers for OpenAPI annotations, generate the JSON file that describes your API, and store it in the storage/api-docs directory by default.

Step 5: Display Swagger UI

Once the documentation is generated, you can display it via a Swagger UI in your browser. The l5-swagger package includes a built-in Swagger UI that you can access by visiting the following URL in your browser:

http://localhost:8000/docs
Enter fullscreen mode Exit fullscreen mode

By default, l5-swagger will serve the Swagger UI at the /docs endpoint, where you can see your API documentation in a user-friendly format.

Customizing the Swagger UI

You can customize how the Swagger UI is served by modifying the config/l5-swagger.php configuration file. For example, you can change the route for the documentation, the title of the Swagger UI page, and more.

'ui' => [
    'path' => 'docs', // The path where the Swagger UI is served
    'title' => 'HookBox API Documentation' // Customize the title of the Swagger UI page
],
Enter fullscreen mode Exit fullscreen mode

Step 6: Serve the Swagger UI Publicly

If you want your API documentation to be publicly available, make sure the route is accessible without authentication. By default, Swagger UI is available to users without any authentication, but you can configure access control for security if needed.

To ensure it is publicly available, add the following to your routes:

Route::get('/docs/hookbox-api-docs.json', function () {
    return response()->json(Storage::get('api-docs/hookbox-api-docs.json'));
})->withoutMiddleware('auth:api');
Enter fullscreen mode Exit fullscreen mode

This will allow public access to your Swagger documentation.

Step 7: Troubleshooting

Here are some common issues and troubleshooting tips:

1. Error: "Unauthorized" when accessing the docs

If you're getting an "Unauthorized" error while trying to access the Swagger UI, make sure that you have disabled authentication for the Swagger route as shown in Step 6.

2. Error: "No OpenAPI info found"

If you're seeing an error like "No OpenAPI info found," ensure that the @OA\Info annotation is correctly placed in your controller or another relevant file. Also, make sure you've run the php artisan l5-swagger:generate command after making any changes.

3. Customization Issues

You can tweak the look and feel of the Swagger UI by modifying the l5-swagger.php configuration file. This file allows you to customize paths, API versioning, and other settings.

Conclusion

By following these steps, you can easily generate and display Swagger (OpenAPI) documentation for your Laravel API using the l5-swagger package. With proper annotations, you provide clear and interactive documentation that helps developers understand how to interact with your API.

Swagger/OpenAPI documentation also makes it easier to onboard new developers and improves collaboration between teams. So, integrate it into your Laravel API and enhance the developer experience!

Image of Timescale

Timescale – the developer's data platform for modern apps, built on PostgreSQL

Timescale Cloud is PostgreSQL optimized for speed, scale, and performance. Over 3 million IoT, AI, crypto, and dev tool apps are powered by Timescale. Try it free today! No credit card required.

Try free

Top comments (0)

Billboard image

Try REST API Generation for Snowflake

DevOps for Private APIs. Automate the building, securing, and documenting of internal/private REST APIs with built-in enterprise security on bare-metal, VMs, or containers.

  • Auto-generated live APIs mapped from Snowflake database schema
  • Interactive Swagger API documentation
  • Scripting engine to customize your API
  • Built-in role-based access control

Learn more

👋 Kindness is contagious

Immerse yourself in a wealth of knowledge with this piece, supported by the inclusive DEV Community—every developer, no matter where they are in their journey, is invited to contribute to our collective wisdom.

A simple “thank you” goes a long way—express your gratitude below in the comments!

Gathering insights enriches our journey on DEV and fortifies our community ties. Did you find this article valuable? Taking a moment to thank the author can have a significant impact.

Okay