How do we share software code that we’ve written with other developers?. By documenting the software’s open APIs and putting it online. That is what swagger does.
Laravel is a popular PHP framework for developing web projects. We can share our Laravel functionalities for other developers to use. This post assumes that you’ve developed open APIs with Laravel.
This post covers Darkaonline Swagger setup on a laravel project.
Make sure composer is installed.
Firstly, composer has to install the swagger on your project. Run the command
composer require “darkaonline/l5-swagger:5.8.*”
We’ll wait for the composer.json to get updated accordingly.
After the installation, run the code below
php artisan vendor:publish --provider "l5Swagger\l5SwaggerServiceProvider"
This sets up Swagger on our project.
php artisan l5-swagger:generate
to generate the swagger documentation. You’ll see an error stack indicating that we’ve not created our project’s swagger annotation. To create this, navigate to app/Http and create the following nested folders Swagger/swagger_models/settings. You should now have app/Http/Swagger/swagger_models/settings
In the settings folder, create 4 files.
In auth.php, paste the following and edit accordingly,
In swagger-v3.php, paste the following and edit accordingly,
In tags.php, paste the following and edit accordingly,
In sample_controller.php, paste the following and edit accordingly,
Run php artisan l5-swagger:generate. This should build with no errors.
The files are also available at https://github.com/4handheld/laravel_swagger_setup_files. They can be cloned and quickly edited.
The auth.php defines how swagger manages data for authenticated/logged in users.
The swagger-v3.php defines the general info about the project.
The tags.php defines the api groups available for open use.
The sample_controller.php is a demo swagger annotation for a sample controller.