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.
Suggested book (affiliate link): Modern PHP: New Features and Good Practices
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.
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.
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.
bootstrap/app.php file, either uncomment, or add the following line. Within the “Create the Application” section – check the comments:
Same file, different line. Under the “Register Container Bindings” section add the following:
Last, but not least
Same file, different day. Under the “Register Service Providers” section, add the following:
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 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
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!