How To Use Darkaonline/l5-Swagger In Laravel

Swagger is a wonderful tool to generate API documentation. So today I am going to show you, how to use Swagger in your Laravel application. We will use DarkaOnLine/L5-Swagger package in Laravel 6.

I am not going to cover Laravel setup in this article so I am assuming that you have up & running Laravel application with some users data.

Step 1:

Open your terminal and run the following command.

composer require "darkaonline/l5-swagger:6.*"

composer require 'zircote/swagger-php:3.*'

Step 2:

Publish config & view files into your Laravel application.

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

Step 3:

Open your .env file and add the below code.

L5_SWAGGER_CONST_HOST=http://127.0.0.1:8000/api
L5_SWAGGER_GENERATE_ALWAYS=true

After DarkaOnLine/L5-Swagger package installed in Laravel, you can check all APIs generated by Swagger which is available to this URL: http://127.0.0.1:8000/api/documentation

Now let’s create a simple API that returns all users. Before we create an API  open your Controller [App\Http\Controllers] and add an annotation like this.

<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Routing\Controller as BaseController;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;

/**
 * @OA\Info(
 *      version="1.0.0",
 *      title="API Documentation",
 *      description="",
 *      @OA\Contact(
 *          email="manan@mananpatel.in"
 *      ),
 *      @OA\License(
 *          name="Apache 2.0",
 *          url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *      )
 * )
 *
 * @OA\Server(
 *      url=L5_SWAGGER_CONST_HOST,
 *      description="API Server"
 * )
 *
 * @OA\Tag(
 *      name="USER",
 *      description="OPERATIONS ABOUT USER"
 * )
*/
class Controller extends BaseController
{
    use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
}

After updating controller.php, let’s create a route in the api.php file.

<?php

use Illuminate\Http\Request;

/*
|--------------------------------------------------------------------------
| API Routes
|--------------------------------------------------------------------------
|
| Here is where you can register API routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| is assigned the "api" middleware group. Enjoy building your API!
|
*/

Route::get('users', 'UsersController@users');

<?php

namespace App\Http\Controllers;

use App\User;
use Illuminate\Http\Request;

class UsersController extends Controller
{
    /**
     * @OA\Get(
     *     path="/users",
     *     tags={"USER"},
     *     summary="GET LIST OF USERS",
     *     operationId="users",
     *     @OA\Response(
     *         response=200,
     *         description="Success"
     *     )
     * )
     */
    public function users()
    {
        $users = User::all();
        return response()->json($users);
    }
}