最长的路Swagger is an open-source language-agnostic framework for describing, documenting, consuming and visualising REST APIs. Swagger was launched and maintain by SmartBear under governance of the Linux Foundation Open API Initiative (OAI).
Who are involved in this project? Google, Microsoft, IBM, PayPal and many more. So why does it matter to have an open standard?
As more consumers, service providers and tooling vendors converge on how to describe REST APIs, life gets better. As a consumer of APIs, you have a standardized way of interacting with APIs. As a service provider, it’s easier for customers to switch to use your services. And as a tooling vendor, you can focus your efforts on making the best possible tools rather than dealing with compatibility issues.[¹]
In this article, we’ll briefly see how to use Swagger in a Laravel application to document REST APIs.
We are going to use the DarkaOnLine/L5-Swagger. This package is based on swagger-PHP and swagger-UI.
Add the package requirement in the require-dev section of the composer.json file of your project.
“require-dev”: {
…
“darkaonline/l5-swagger”: “~3.0”
}
Run composer update to install version 3.1.2, which is the latest version at the time of this writing. Please note that earlier versions don’t support Laravel 5.1
composer update “darkaonline/l5-swagger”
You need to register the L5SwaggerService provider in config/app.php using the line L5Swagger\L5SwaggerServiceProvider::class
Now run the publish command to generate config file and resources.
php artisan l5-swagger:publish
Add .gitignore to the following folders, as we don’t need to include resource files in the repository. They will be added to our project every time we run the publish command.
./public/vendor/l5-swagger ./resources/views/vendor/l5-swagger
Add .gitignore in the above mentioned folders.
* !.gitignore
You also need to add ./storage/api-docs folder in the global .gitignore, as the contents of this folder get overridden every time documentation generates.
Note — when cloning the project, we need to regenerate the vendor resources otherwise swagger UI will not work. To do this run the publish command.
php artisan l5-swagger:publish
Okie, everything is set, let’s add some swagger documentation to our code base.
Add the following at the top level controller or base controller to define base path, project details etc. @SWG\Info is required.
/** * @SWG\Swagger( * basePath="/calculate-rates", * @SWG\Info( * title="Customer rate calculator API", * version="1.0.0" * ) * ) */
Let’s assume we have an endpoint that lists all the rates for a customer and expects customer Id to be provided as part of the URI path and filter as an optional query string.
/**
* @SWG\Get(
* path="/customer/{customerId}/rate",
* summary="List customer rates",
* operationId="getCustomerRates",
* @SWG\Parameter(
* name="customerId",
* in="path",
* description="Target customer.",
* required=true,
* type="integer"
* ),
* @SWG\Parameter(
* name="filter",
* in="query",
* description="Filter results based on query string value.",
* required=false,
* enum={"active", "expired", "scheduled"},
* type="string"
* ),
* @SWG\Response(response=200, description="successful operation"),
* @SWG\Response(response=406, description="not acceptable"),
* @SWG\Response(response=500, description="internal server error")
* )
*
*/
If you have already enabled the automatic document generation in the .envfile then you don’t have to do anything, otherwise add the following line in the .env file
L5_SWAGGER_GENERATE_ALWAYS=true
Or run the generate command
php artisan l5-swagger:generate
Browse to http://service-url/api/documentation for swagger documentation. If everything is working as it should be then you should see something similar.
Expand operations
Provide a valid customer Id and press the ‘Try it out!’, Voila!. It will show the CURL command and response headers which are very handy. We don’t even need to look into the code to find out what are the inputs and outputs for an endpoint.
Look into swagger-php website, pet store example and swagger explained for more detail examples.
I hope you find this article useful.
