Justin Philip DevBook

Swagger Implementation With Laravel

Swagger Implementation With Laravel

Justin Philip's photo
Justin Philip
·

5 min read

Swagger is the most popular, and widely used tool for implementing the OpenAPI specification. It generates interactive API documentation that lets your users try out the API calls directly in the browser.

Laravel Swagger Library : github.com/DarkaOnLine/L5-Swagger

Lumen Swagger Library : github.com/DarkaOnLine/SwaggerLume

Steps :

Install the Swagger according to the Laravel/Lumen version that you have installed. For Laravel composer require "darkaonline/l5-swagger:5.8.*"

For Lumen :
composer require "darkaonline/swagger-lume:5.6.*"

Follow the installation and configuration process of Laravel/Lumen Swagger as per above packages. Laravel : github.com/DarkaOnLine/L5-Swagger/wiki/Inst..

Lumen :
https://github.com/DarkaOnLine/SwaggerLume/#installation

We need to create Swagger Annotations. Below are general specifications.

@OA() refers to what kind of HTTP method we’ll use. The method can be GET, POST, PUT or DELETE.

@OA\Parameter refers to the name of the parameters that will pass to API.

@OA\Response() which kind of response and code will we return if the data is correct or incorrect.

It's good to checkout various annotations in Swagger Annotations examples below:

github.com/DarkaOnLine/L5-Swagger/blob/mast..

You can create annotations for Controllers or Models

In this example, i'm creating a SwaggerController.php for documenting my API(s), basically all my routes.

Below is an exampleController with some annotations added. You can extend with more OA annotations for Request params, and Response params to document properly.

SwaggerController.php Example

<?php

namespace App\Http\Controllers;

use Laravel\Lumen\Routing\Controller as BaseController;

/**
* @OA\Info(
*      version="1.0.0",
*      title="VLS Monitor Microservice API Documentation",
*      description="Sms and email sending functionality",
*      @OA\Contact(
*          email="admin@website.com"
*      ),
* )
*/

/**
*  @OA\Server(
*      url="http://localhost/website/public/",
*      description="Host"
*  )
*
*/

/**
* @OA\SecurityScheme(
*   securityScheme="Authorization",
*   type="apiKey",
*   in="header",
*   name="Authorization"
* )
*/


/**
* @OA\Get(
*     path="/",
*     summary="Get App Version",
*     tags={"General"},
*    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    )
* )
*/

 /**
* @OA\Get(
*     path="/key",
*     summary="Get App Key",
*     tags={"General"},
 *    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    )
* )
*/

  /**
* @OA\Get(
*     path="/logs",
*     summary="To Log",
*     tags={"Logs"},
*    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    )
* )
*/

   /**
* @OA\Get(
*     path="/test",
*     summary="To Test",
*     tags={"Test"},
*    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    )
* )
*/

    /**
* @OA\Post(
*     path="/create-project",
*     summary="Create a project",
*     tags={"Project API"},
*    @OA\Parameter(
*           name="name",
*           in="query",
*           required=true,
*           @OA\Schema(
*                 type="string"
*           )
*     ),
*    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    ),
*      security={
*         {"Authorization":{}}
*     },
* )
*/

/**
* @OA\Post(
*     path="/send-mail-vls",
*     summary="Send mail to vls team without authentication",
*     tags={"Mail"},
*   
*     @OA\Parameter(
*           name="content",
*           in="query",
*           required=true,
*           @OA\Schema(
*                 type="string"
*           )
*     ),
*    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    )
* )
*/

      /**
* @OA\Post(
*     path="/template/store",
*     summary="To store the template",
*     tags={"Templates"},
*     @OA\Parameter(
*           name="content",
*           in="query",
*           required=true,
*           @OA\Schema(
*                 type="string"
*           )
*     ),
*     @OA\Parameter(
*           name="project_id",
*           in="query",
*           required=true,
*           @OA\Schema(
*                 type="string"
*           )
*     ),
 *    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    ),
*     security={
*         {"Authorization":{}}
*     },
* )
*/

      /**
* @OA\Post(
*     path="/template/update",
*     summary="To update the template",
*     tags={"Templates"},
*    @OA\Parameter(
*           name="content",
*           in="query",
*           required=true,
*           @OA\Schema(
*                 type="string"
*           )
*     ),
*     @OA\Parameter(
*           name="templateId",
*           in="query",
*           required=true,
*           @OA\Schema(
*                 type="string"
*           )
*     ),
 *    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    ),
*     security={
*         {"Authorization":{}}
*     },
* )
*/

      /**
* @OA\Post(
*     path="/template/get",
*     summary="To get the template",
*     tags={"Templates"},
*     @OA\Parameter(
*           name="templateId",
*           in="query",
*           required=true,
*           @OA\Schema(
*                 type="string"
*           )
*     ),
*     @OA\Parameter(
*           name="project_id",
*           in="query",
*           required=true,
*           @OA\Schema(
*                 type="string"
*           )
*     ),
*    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    ),
*     security={
*         {"Authorization":{}}
*     },
* )
*/

      /**
* @OA\Post(
*     path="/set-schedule",
*     summary="Set the schedule task",
*     tags={"Task"},
*    @OA\Response(
*      response=200,
*       description="Success",
*   ),
*   @OA\Response(
*      response=401,
*       description="Unauthenticated"
*   ),
*   @OA\Response(
*      response=400,
*      description="Bad Request"
*   ),
*   @OA\Response(
*      response=404,
*      description="not found"
*   ),
*    @OA\Response(
*          response=403,
*          description="Forbidden"
*    ),
*     security={
*         {"Authorization":{}}
*     },
* )
*/

class SwaggerController extends BaseController
{
   //
}

Now, we need to generate JSON /YAML with a complete view assets file to generate Swagger. Run below command:

For Laravel :
php artisan l5-swagger:generate
Lumen :
php artisan swagger-lume:generate

Screenshot 2021-02-08 at 10.35.08 AM.png

The API documentation by default is setup at ‘/api/documentation’ route as below

Now, you have Swagger API Documentation LIVE !

References : blog.quickadminpanel.com/laravel-api-docume.. dev.to/avsecdongol/laravel-api-documentatio.. petstore.swagger.io/#