Generating API Documentation with OpenAPI Swagger

In this lesson, we will check another tool for generating API documentation called Laravel Swagger using the DarkaOnLine/L5-Swagger package.

Swagger is an open standard for APIs, not specifically for Laravel or PHP. It is general for all APIs. Now, swagger is called OpenAPI, but you can find it in both names on the internet.

This package works similarly to Scribe by adding docblocks and running an artisan command to generate documentation.

On March 13, 2024, this package had no support for Laravel 11.

You can install Swagger via Composer.

composer require "darkaonline/l5-swagger"

And publish config with views if needed.

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

You can specify global configuration in the config, for example, the title.

config/l5-swagger.php:

return [
    'default' => 'default',
    'documentations' => [
        'default' => [
            'api' => [
                'title' => 'L5 Swagger UI', 
                'title' => 'E-Shop Catalog API Docs', 
            ],
 
            // ...
        ],
    ],
 
    // ...
];

In the .env, you should set the L5_SWAGGER_CONST_HOST. This is the URL the button Try it out in the docs would use. You can reuse the APP_URL.

.env:

// ...
 
L5_SWAGGER_CONST_HOST=${APP_URL}/api

Then, you need to specify somewhere in the global Controller information about the document. At least the @OA\Info is required.

app/Http/Controller.php:

/**
 * @OA\Info(
 *     version="1.0.0",
 *     title="E-Shop Catalog",
 *     description="API Documentation",
 * )
 */
class Controller extends BaseController 
{
    use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
}

Other options are optional. If something is required when generating, you will get an error. And finally, for every method in the Controller, you can specify the options.

app/Http/Controllers/Api/CategoryController.php:

<?php
 
namespace App\Http\Controllers\Api;
 
use App\Models\Category;
use Illuminate\Support\Str;
use App\Http\Controllers\Controller;
use App\Http\Resources\CategoryResource;
use App\Http\Requests\StoreCategoryRequest;
 
class CategoryController extends Controller
{
    /**
     * @OA\Get(
     *     path="/categories",
     *     tags={"Categories"},
     *     summary="Get list of categories",
     *     @OA\Response(
     *         response=200,
     *         description="Successful operation",
     *     ),
     *     @OA\Response(
     *          response=401,
     *          description="Unauthenticated",
     *     ),
     *     @OA\Response(
     *          response=403,
     *          description="Forbidden",
     *     )
     * )
     */
    public function index() 
    {
        abort_if(! auth()->user()->tokenCan('categories-list'), 403);
 
        return CategoryResource::collection(Category::all());
    }
 
    // ...
}

After generating the documentation

php artisan l5-swagger:generate

We should see a similar result to the image below:

The Swagger package is more complex than the Scribe, but it also has more features and uses the standard OpenAPI. Also, if your API grows big with swagger, it will be faster to review the documentation.

For more information and examples, check the package repository on GitHub.

Generating API Documentation with Scribe Versioning your API: from V1 to V2 and Beyond

Course Content

How to Build Laravel 11 API From Scratch

Generating API Documentation with OpenAPI Swagger

Course Content

Getting Data via Laravel API

Posting Data via Laravel API

Authentication and Authorization

Additional Various Topics