How to write Swagger documentation for Laravel API. Tips & examples
--
API documentation becomes very necessary when you split the team into Backend and Frontend. And even more when you divide your monorepo into parts or even microservices.
I will show you how easily create API documentation for your Laravel API using swagger.
Let’s start. I prefer using this package. This package is a wrapper of Swagger-php and swagger-ui adapted to work with Laravel.
composer require "darkaonline/l5-swagger"
Then publish config and all view files:
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
Next, open a config/l5-swagger.php file. Let’s walk through essential keys:
- routes.api — This is an URL for accessing documentation UI. Your frontend team will be using it to access documentation. By default, it is api/documentation . I prefer changing it to something smaller like api/docs
- generate_always — I prefer disabling it as it will generate docs on the fly. Not useful with big API. You can always manually run php artisan l5-swagger:generate
Those are the most important to start. Now if you try to create docs using this command
php artisan l5-swagger:generate
It will return an error
Required @OA\Info() not found
That means that you have to create that notation first. So let’s add it. I prefer creating Abstract controller for an API, but you can add this to app/Http/Controllers/Controller.php
/**
* @OA\Info(
* title="Your super ApplicationAPI",
* version="1.0.0",
* )
*/class Controller extends BaseController
{
use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
}
Next, we need to add docs for at least one route. Let’s add it for app/Http/Controllers/Auth/LoginController.php:
/**
* @OA\Post(
* path="/login",
* summary="Sign in",
* description="Login by email, password",
* operationId="authLogin",
* tags={"auth"},
* @OA\RequestBody(
* required=true,
* description="Pass user credentials",
* @OA\JsonContent(
* required={"email","password"},
* @OA\Property(property="email", type="string", format="email", example="user1@mail.com"),
* @OA\Property(property="password"…