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.
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: true
Swagger does now have enough information to work with, so it’s time to document the API controllers (
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
./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:
If you now go to
http://laravel.localhost/swagger/index.html, Swagger will appear and your API is testable.
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.