Generate beautiful RESTful Laravel API documentation with Swagger

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.

Installation

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
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

What’s next?