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 😉