How to integrate Swagger in Lumen/Laravel for REST API? - laravel-5.4

Question

I have built some REST API in Lumen micro framework and it's working fine. Now I want to integrate Swagger into it so the API will be well documented on future use. Has anyone done this?

Answer 1

Steps to follow for Laravel Lumen 5.7 with swagger using OpenApi 3.0 specs (this governs the way you write annotations so that swagger documentation is generated)
The steps were written a while ago but they still work with Laravel Lumen 6.X, 7.X and 8.X
I reached this adjusting on #black-mamba answer in order to make it work.
1. Install swagger-lume dependency (which also installs swagger)
composer require "darkaonline/swagger-lume:5.6.*"
2. Edit bootstrap/app.php file
make sure $app->withFacades(); is NOT commented (around line 26)
in Create The Application section add the following before Register Container Bindings section
$app->configure('swagger-lume');
in Register Service Providers section add
$app->register(\SwaggerLume\ServiceProvider::class);
3. Publish configuration file for swagger-lume
php artisan swagger-lume:publish
4. Add annotations to your code
For example in your app/Http/Controllers/Controller.php you could have the general part of the documentation
<?php
namespace App\Http\Controllers;
use Laravel\Lumen\Routing\Controller as BaseController;
class Controller extends BaseController
{
/**
* #OA\Info(
* title="Example API",
* version="1.0",
* #OA\Contact(
* email="support#example.com",
* name="Support Team"
* )
* )
*/
}
And inside each of your controllers you should have the appropriate annotations above each public method
<?php
namespace App\Http\Controllers;
class ExampleController extends Controller
{
/**
* #OA\Get(
* path="/sample/{category}/things",
* operationId="/sample/category/things",
* tags={"yourtag"},
* #OA\Parameter(
* name="category",
* in="path",
* description="The category parameter in path",
* required=true,
* #OA\Schema(type="string")
* ),
* #OA\Parameter(
* name="criteria",
* in="query",
* description="Some optional other parameter",
* required=false,
* #OA\Schema(type="string")
* ),
* #OA\Response(
* response="200",
* description="Returns some sample category things",
* #OA\JsonContent()
* ),
* #OA\Response(
* response="400",
* description="Error: Bad request. When required parameters were not supplied.",
* ),
* )
*/
public function getThings(Request $request, $category)
{
$criteria= $request->input("criteria");
if (! isset($category)) {
return response()->json(null, Response::HTTP_BAD_REQUEST);
}
// ...
return response()->json(["thing1", "thing2"], Response::HTTP_OK);
}
}
5. Generate swagger documentation
php artisan swagger-lume:generate
Run this each time you update the documentation
see:
https://zircote.github.io/swagger-php/
https://github.com/DarkaOnLine/SwaggerLume
https://swagger.io/specification/

Answer 2

I had really hard time in learning how to use it. Here I'm going to share some of the things I did to get it working
Use this wrapper
Run this command in your terminal:
composer require "darkaonline/swagger-lume:5.5.*"
Or older version from the repo linked if this doesn't work for you
Then from the repo follow these steps:
Open your bootstrap/app.php file and:
uncomment this line (around line 26) in Create The Application
section:
$app->withFacades(); add this line before Register Container Bindings section:
$app->configure('swagger-lume'); add this line in Register Service Providers section:
$app->register(\SwaggerLume\ServiceProvider::class);
Then you'll need to use annotations for your project instead of YAML or JSON
For more
Create a Annotation.php file in your app folder add the following a sample
/**
* #SWG\Swagger(
* basePath="/",
* schemes={"http"},
* #SWG\Info(
* version="1.0.0",
* title="HAVE MY BOOKS",
* #SWG\Contact(
* email="example#test.com"
* ),
* )
* )
*/
/**
* #SWG\Get(
* path="/",
* summary="Version",
* #SWG\Response(
* response=200,
* description="Working"
* ),
* #SWG\Response(
* response="default",
* description="an ""unexpected"" error"
* )
* )
*/
Then run
php artisan swagger-lume:publish
Then run
php artisan swagger-lume:generate
This generates JSON which can be accessed from your localhost:8000 or whichever port you are serving your LUMEN service
Note: after creating an issue in the repo I found that to access you'll need to serve or run using
php -S localhost:8000 public/index.php
Because of some PHP routing issue with php -S localhost:8000 public