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

user_7188473 0
Viewed 20657

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?

laravel-5.4 lumen
2 Answers

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:

user_44448240
Related