Automatically Generate Docs For Your Entire Laravel App In Under 5 Minutes

  SC     17 Dec 2018
Do you document your API application? Without a proper API documentation, your peers or coworkers have no idea how to discover the API endpoints and their usages.

L5 Swagger

Swagger is the most popular framework of API developer tools for the OpenAPI Specification(OAS). Swagger-php generates interactive Swagger documentation for RESTful API. Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API. L5 Swagger is a package adapts swagger-php and swagger-ui to work with Laravel 5.


Install l5-swagger package in your Laravel 5 project via Composer.
composer require darkaonline/l5-swagger
After the installation, you can find the l5-swagger commands with artisan command.
php artisan list
  l5-swagger:generate        Regenerate docs
  l5-swagger:publish         Publish config, views
  l5-swagger:publish-config  Publish config
  l5-swagger:publish-views   Publish views
Before you start to develop with the package, you publish its files.

Publishing files

Publish the package files with artisan command.
php artisan l5-swagger:publish
Publishing all files
Copied File [/vendor/darkaonline/l5-swagger/config/l5-swagger.php] To [/config/l5-swagger.php]
Copied Directory [/vendor/darkaonline/l5-swagger/resources/views] To [/resources/views/vendor/l5-swagger]
Publishing complete.

First API endpoint

Now, you create an endpoint and automate the documentation. Create a resourceful controller named SampleController.
php artisan make:controller SampleController --resource
Controller created successfully.
Swagger works along with the object inheritance. On the parent object, you declare the base path and general information like title and version.
// app/Http/Controllers/Controller.php
 * @SWG\Swagger(
 *   basePath="/api",
 *   @SWG\Info(
 *     title="Core API",
 *     version="1.0.0"
 *   )
 * )
class Controller extends BaseController
In the SampleController’s index method, you response a text in JSON format. Then, you declare the endpoint and the summary, and the possible responses.
// app/Http/Controllers/SampleController.php
 * @SWG\Get(
 *   path="/sample",
 *   summary="Sample",
 *   @SWG\Response(response=200, description="successful operation")
 * )
 * Display a listing of the resource.
 * @return \Illuminate\Http\Response
public function index()
    return response()->json('Ok');

Generate the documentation

By executing the l5-swagger:generate command, the documentation will be generated.
php artisan l5-swagger:generate Regenerating docs
After the document generation, head to the browser and hit the address bar with http://localhost:8080/api/documentation Do you document your API application? Tell me in the comment below. By the way if you are looking for a job online in malaysia to try out your laravel chops, sign up here!