aubds / 1-laravel-swagger-ui

Add Swagger UI to a Laravel application.

Laravel Swagger UI

This package makes it easy to make your project's Swagger (OpenAPI v3 JSON or YAML) file accessible in a Swagger UI right in your Laravel application.

The Swagger UI will automatically use your current project environment. It will set your api's base url to the active base url. Possible oauth2 configuration, such as urls and client-id/client-secret, can also be injected in Swagger UI via the configuration file.

Installation

You can install the package via composer:

composer require nextapps/laravel-swagger-ui

After installing Laravel Swagger UI, publish its service provider and configuration file using the swagger-ui:install Artisan command.

php artisan swagger-ui:install

Usage

The Swagger UI is exposed at /swagger. By default, you will only be able to access it in the local environment. Within your app/Providers/SwaggerUiServiceProvider.php file, there is a gate method. This authorization gate controls access to Swagger UI in non-local environments. You can modify this gate as needed to restrict access to your Swagger UI and Swagger (OpenAPI v3) file:

/**
 * 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 config/swagger-ui.php file, you edit the path to the Swagger UI and the location of the Swagger (OpenAPI v3) file. By default, the package expects to find the OpenAPI file in 'resources/swagger' directory.

// in config/swagger-ui.php

return [
    // ...

    'path' => 'swagger',

    'file' => resource_path('swagger/openapi.json'),

    // ...
];

You also have the option to customize the oauth setup. By default, the oauth paths are configured based on Laravel Passport. You can also set a client ID and client secret. These values will be automatically prefilled in the authentication view in Swagger UI.

// in config/swagger-ui.php

return [
    // ...

    'oauth' => [
        'token_path' => 'oauth/token',
        'refresh_path' => 'oauth/token',
        'authorization_path' => 'oauth/authorize',

        'client_id' => env('SWAGGER_UI_OAUTH_CLIENT_ID'),
        'client_secret' => env('SWAGGER_UI_OAUTH_CLIENT_SECRET'),
    ];

    // ...
];

Testing

composer test

Linting

composer lint

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Günther Debrauwer
• All Contributors

License

The MIT License (MIT). Please see License File for more information.