Adding Swagger UI to Your Laravel Application

Hello!

In this article, we will show you how to integrate Swagger UI into your Laravel application so that you can easily view and interact with your Swagger (OpenAPI v3) file right in your application. Swagger UI provides a convenient interface for testing and documenting APIs, making it much easier to work with your API and its documentation.

Plastic bag Swagger UI for Laravel makes it easy to access your project's Swagger file (JSON or YAML OpenAPI v3) via the Swagger UI directly in your Laravel application. All you need to do is place the OpenAPI file in a directory resources/swagger/openapi.json (this can be customized) and follow the path /swagger in the local project environment.

What I particularly like about this package is that it automatically updates Swagger UI to use the current project environment, including setting the API base URL to the Laravel project base URL. The package also allows you to configure OAuth2, which can be integrated into Swagger UI via the package's configuration file.

URL /swagger available locally, and you can also define custom access logic to authorize and control access to Swagger UI in non-local environments.

Installation

First, you need to install the Swagger UI package for Laravel using Composer:

composer require nextapps/laravel-swagger-ui

Once the package is installed, publish the service provider and configuration file using the Artisan command:

php artisan swagger-ui:install

Usage

Swagger UI will be available at /swagger. By default, it can only be accessed in the local environment. In the file app/Providers/SwaggerUiServiceProvider.php the method is found gatewhich controls access to Swagger UI in non-local environments. You can configure this method to restrict access to your Swagger UI and Swagger file (OpenAPI v3):

<?php
/**
 * Register the Swagger UI gate.
 *
 * This gate determines who can access Swagger UI in non-local environments.
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewSwaggerUI', function ($user = null) {
        return in_array(optional($user)->email, [
            //
        ]);
    });
}

In the published file config/swagger-ui.php you can configure the path to the Swagger UI and the location of the Swagger file (OpenAPI v3). By default, the package expects to find the OpenAPI file in the directory resources/swagger. You can also specify a URL if the OpenAPI file is not directly in the Laravel project. You can also define multiple versions of the same API here.

<?php
// в config/swagger-ui.php
return [
// ...
<span class="hljs-string">'path'</span> =&gt; <span class="hljs-string">'swagger'</span>,

<span class="hljs-string">'versions'</span> =&gt; [
    <span class="hljs-string">'v1'</span> =&gt; <span class="hljs-title function_ invoke__">resource_path</span>(<span class="hljs-string">'swagger/openapi.json'</span>)
],

<span class="hljs-comment">// ...</span>

];

By default, the package will configure the server URL and OAuth URL in the OpenAPI file to the base URL of the Laravel application. This can be disabled in the configuration.

<?php
// в config/swagger-ui.php
return [
// ...
<span class="hljs-string">'modify_file'</span> =&gt; <span class="hljs-literal">true</span>,

<span class="hljs-comment">// ...</span>

];

You can also specify an OAuth client ID and client secret. These values ​​will be automatically populated into the authentication form in Swagger UI.

<?php
// в config/swagger-ui.php
return [
// ...
<span class="hljs-string">'oauth'</span> =&gt; [
    <span class="hljs-string">'token_path'</span> =&gt; <span class="hljs-string">'oauth/token'</span>,
    <span class="hljs-string">'refresh_path'</span> =&gt; <span class="hljs-string">'oauth/token'</span>,
    <span class="hljs-string">'authorization_path'</span> =&gt; <span class="hljs-string">'oauth/authorize'</span>,

    <span class="hljs-string">'client_id'</span> =&gt; <span class="hljs-title function_ invoke__">env</span>(<span class="hljs-string">'SWAGGER_UI_OAUTH_CLIENT_ID'</span>),
    <span class="hljs-string">'client_secret'</span> =&gt; <span class="hljs-title function_ invoke__">env</span>(<span class="hljs-string">'SWAGGER_UI_OAUTH_CLIENT_SECRET'</span>),
],

<span class="hljs-comment">// ...</span>

];

Testing

To run tests, use the command:

composer test

You can learn more about this package, get full installation instructions, and view the source code on GitHub at: nextapps-be/laravel-swagger-ui.

That's it! Now you know how to add Swagger UI to your Laravel application and customize it to your needs. If you have any questions or need additional help, don't hesitate to reach out. Happy developing!