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');
We are very close to generating users API in Swagger so now let’s create UsersController class [App\Http\Controllers] and create users() method and update method comments as per the below example.
<?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);
}
}
Now If everything works perfectly you can see the documentation like this with the users route.
Keep visiting for new stuff and give your feedback.
Happy Coding 😉
