Categories

Lumen Swagger integration

Intro

This guide is the second part to a miniseries, that I unintentionally started – “Integrating Swagger into stuff”. Well, be on the look-out for a “Swagger in a toaster” next week.

Overview

Anyway, let’s get to the point. This guide will be somewhat similar to the Swagger & Laravel one. There are a few key differences that I would like to point out here, as you might find them useful.

Guide

Stage 1 – The package

I will be using a customized version of the DarkaOnLine package for this guide, for a couple of crucial reasons. Firstly I need to make sure that my docs are accessible from the staging/production environment, which in my current situation live on a different server, from the app itself. Which means – lots and lots of CORS issues. To circumvent them, and to allow the cross-origin access, I have forked the base package, and have included some zest in it. We’ll get to that later.

BTW, the package can be found here: click, and the source here: click

Right, so grab the package and use it in your project with the following command:

composer require maxim-sarandev/lumen-swagger-cors

Stage 2 – Lumen specific setup

“What is my purpose?” asked this guide. “Lumen is weird” is the answer. To get Swagger up-and-running we need to do a few things.

Firstly

Within the bootstrap/app.php file, either uncomment, or add the following line. Within the “Create the Application” section – check the comments:

$app->withFacades();

Next

Same file, different line. Under the “Register Container Bindings” section add the following:

$app->configure('swagger-lume');

Last, but not least

Same file, different day. Under the “Register Service Providers” section, add the following:

$app->register(\SwaggerLume\ServiceProvider::class);

The mighty config

To configure the integration, we need a place to edit things right? Right, run the following command to generate the config file:

php artisan swagger-lume:publish-config

This should’ve generated a file within the config section of your app. Let me show you where the CORS thing comes into play. If we take a look at the end of the file, you can see the custom key cors_data, within it a sub-key picks up a pre-defined value from the .env file, or returns a null. Here’s the snippet:

'cors_data' => [
    // Currently supports a single URL
    'allowedOrigin' => env('SWAGGER_LUME_CORS_ACCESS_ORIGIN', null),
]

The env file

The last thing we need to do is to add the keys to our env file. These will define the CORS URL, the syntax language version (level), and the last flag will ensure that our manually created work will not go to waste (disabling auto generation):

SWAGGER_GENERATE_ALWAYS=false
SWAGGER_VERSION=3.0
SWAGGER_LUME_CORS_ACCESS_ORIGIN=example.com

Easy as that. Great, now all you have to do is add your /api-docs.json file, that actually contains the Swagger definitions.

Your folder structure should look like so:

/storage
|-> /api-docs
    |-> /api-docs.json
| (...)

Clicking all the things

The hard part is done, let’s see it. In order to do so, we need to ask Swagger, kindly of course, to generate us a view. Command:

php artisan swagger-lume:publish-views

Conclusion

That’s it. Nothing really confusing, especially if you’ve had prior experience with Swagger before. The only convoluted part may seem to be the CORS customisation, but that is extremely simple as well.

Special thanks to DarkaOnLine for doing the hard work for us!

Happy Coding!

Home