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

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