Complete Setup of Swagger on Laravel 5.x

Joseph
Joseph
May 23 · 2 min read

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.

Next, run

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.

  1. auth.php
  2. swagger-v3.php
  3. tags.php
  4. sample_controller.php

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.

Quick Notes:

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.