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.
Swagger is the most popular framework of API developer tools for the OpenAPI Specification(OAS).
generates interactive Swagger documentation for RESTful 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
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.
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]
First API endpoint
Now, you create an endpoint and automate the documentation.
Create a resourceful controller named
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.
* title="Core API",
class Controller extends BaseController
’s index method, you response a text in
format. Then, you declare the endpoint and the summary, and the possible responses.
* @SWG\Response(response=200, description="successful operation")
* Display a listing of the resource.
* @return \Illuminate\Http\Response
public function index()
Generate the documentation
By executing the
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!