read

Every time we built Rails APIs at empuxa, we made use of Swagger and Swagger UI, an incredible way to easily document and test your APIs.

This is what Swagger UI looks like. The whole API is testable within the browser.

Back to PHP, I missed the tools a lot. All packages that promised an easy integration via Composer either failed to work or were built on Swagger 1.2—which is incompatible to Swagger 2.0. Disappointed of the current situation, but still too lazy to create an own PHP package, I came up with following static workaround (that will also work for non-Laravel projects):

Update your Composer packages

No matter what kind of framework is used, we always need the Swagger-PHP package to parse our files:

composer require zircote/swagger-php

Write the Docs

As far as I know, there’s no tool for PHP that automatically adds the minimum required Swagger information to your classes, so you have to do it manually. But once it’s done, it generally should be copy and paste with only small modifications.

Controllers

Before you can start to generate our docs, you have to configure Swagger. The code below is an example of information that has to be defined to make it run. You don’t need to have classes, a simple PHP file that contains the comment will also work. However, I chose to create a controller that is extended by all my API controllers (app/Http/ApiController.php) to store my Swagger config:

Swagger does now have enough information to work with, so it’s time to document the API controllers (app/Http/Controllers/Api/DashboardController.php):

Models

The syntax for models is quite different than the controllers’ and I personally don’t include them in my docs, so this is just an example of how it should work:

Create the Docs

All PHP files do now have the required information, but it’s not yet specified, where the docs shall be written to. I chose public/api as location, so create the missing folder with mkdir public/api. Afterwards, type the following command to generate the swagger.jsonfile:

./vendor/bin/swagger /Users/YOUR-USER/Sites/laravel/app/Http --output public/api/

Feel free to change paths to your needs. Running Swagger on /Users/YOUR-USER/Sites/laravel/app will, for example, include the models.

Install Swagger UI

To avoid problems with future updates due to overwritten settings, I decided to only manually update the Swagger UI files from time to time. Download the package from GitHub, extract the contents and copy the dist/* folder to public/swagger/*. Finally, modify the URL in the index.html file to your environment’s URL, which is in my case:

http://laravel.localhost/api/swagger.json

If you now go to http://laravel.localhost/swagger/index.html, Swagger will appear and your API is testable.

The brand new API doc.

It might not be the most elegant solution, because the setup is not flexible at all, but was a nice compromise between time and effort. Here’s by the way the final swagger.json.

Marco Raddatz

Marco Raddatz

Published

Image
Marco Raddatz #TechnicalProjectManagement #SoftwareDevelopment #Berlin Back to Overview