Skip to content

Installation & Configuration

Jump to bottom
Darius Matulionis edited this page Jan 6, 2025 · 10 revisions

Installation

Laravel Swagger UI OpenAPI Spec compatibility L5-Swagger
7.x, 8.x 9.x 10.x and 11.x 3 3.0 composer require "darkaonline/l5-swagger"

Multi API documentation support
See changes
See migration instructions
7.x 3 3.0, 2.0 composer require "darkaonline/l5-swagger:7.*"

⚠️ !!! run composer require 'zircote/swagger-php:2.*' if you need old @SWG (SWAGGER annotations) support. !!!
6.0.x 3 3.0, 2.0 composer require "darkaonline/l5-swagger:6.*"

⚠️ !!! run composer require 'zircote/swagger-php:2.*' if you need old @SWG (SWAGGER annotations) support. !!!
5.8.x 3 3.0, 2.0 composer require "darkaonline/l5-swagger:5.8.*"

⚠️ !!! run composer require 'zircote/swagger-php:2.*' if you need old @SWG (SWAGGER annotations) support. !!!
5.7.x OR 5.6.x 3 3.0, 2.0 composer require "darkaonline/l5-swagger:5.7.*"

⚠️ !!! run composer require 'zircote/swagger-php:2.*' if you need old @SWG (SWAGGER annotations) support. !!!
5.6.x 3 2.0 composer require "darkaonline/l5-swagger:5.6.*"
5.5.x 3 2.0 composer require "darkaonline/l5-swagger:5.5.*"
5.4.x 3 2.0 composer require "darkaonline/l5-swagger:5.4.*"
5.4.x 2.2 1.1, 1.2, 2.0 composer require "darkaonline/l5-swagger:~4.0"
5.3.x 2.2 1.1, 1.2, 2.0 composer require "darkaonline/l5-swagger:~3.0"
5.2.x 2.2 1.1, 1.2, 2.0 composer require "darkaonline/l5-swagger:~3.0"
5.1.x 2.2 1.1, 1.2, 2.0 composer require "darkaonline/l5-swagger:~3.0"

For Laravel >=5.5, no need to manually add L5SwaggerServiceProvider into the config. It uses a package auto-discovery feature. Skip this if you are on >=5.5, if not:

Open your AppServiceProvider (located in app/Providers) and add this line in register function

$this->app->register(\L5Swagger\L5SwaggerServiceProvider::class);

or open your config/app.php and add this line in providers section

L5Swagger\L5SwaggerServiceProvider::class,

You can access your documentation at /api/documentation endpoint.

Swagger/OpenApi annotations and generating documentation

In order to generate the Swagger/OpenApi documentation for your API, Swagger offers a set of annotations to declare and manipulate the output. These annotations can be added to your controller, model, or even a separate file. An example of OpenApi annotations can be found here. For more info check out Swagger's "pet store" example or the Swagger OpenApi Specification.

After the annotations have been added you can run php artisan l5-swagger:generate to generate the documentation.

Alternatively, you can set L5_SWAGGER_GENERATE_ALWAYS to true in your .env file so that your documentation will automatically be generated. Make sure your settings in config/l5-swagger.php are complete.

Configuration

For versions >= 6

You can publish L5-Swagger's config and view files into your project by running:

$ php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
$ php artisan l5-swagger:generate

For versions < 5.5

  • Run php artisan l5-swagger:publish to publish everything
  • Run php artisan l5-swagger:publish-config to publish configs (config/l5-swagger.php)
  • Run php artisan l5-swagger:publish-assets to publish swagger-ui to your public folder (public/vendor/l5-swagger)
  • Run php artisan l5-swagger:publish-views to publish views (resources/views/vendor/l5-swagger) - only for versions <= 4.0
  • Run php artisan l5-swagger:generate to generate docs
Clone this wiki locally