Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wotzebra/laravel-swagger-ui
Add Swagger UI to a Laravel application.
https://github.com/wotzebra/laravel-swagger-ui
Last synced: 8 days ago
JSON representation
Add Swagger UI to a Laravel application.
- Host: GitHub
- URL: https://github.com/wotzebra/laravel-swagger-ui
- Owner: wotzebra
- License: mit
- Created: 2020-10-01T09:31:24.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2024-09-26T11:44:44.000Z (about 1 month ago)
- Last Synced: 2024-10-25T01:51:52.298Z (13 days ago)
- Language: PHP
- Size: 119 KB
- Stars: 193
- Watchers: 9
- Forks: 24
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Laravel Swagger UI
[](https://packagist.org/packages/wotz/laravel-swagger-ui)
[](https://packagist.org/packages/wotz/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:
```bash
composer require wotz/laravel-swagger-ui
```
After installing Laravel Swagger UI, publish its service provider and configuration file using the `swagger-ui:install` Artisan command.
```bash
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:
```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 `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. You can also provide an url if the OpenAPI file is not present in the Laravel project itself.
This is also where you can define multiple versions for the same api.
```php
// in config/swagger-ui.php
return [
// ...
'path' => 'swagger',
'versions' => [
'v1' => resource_path('swagger/openapi.json')
],
// ...
];
```
By default the package will customize the server url and the oauth urls in the OpenAPI file to the base url of the Laravel application. This can be disabled in the config.
```php
// in config/swagger-ui.php
return [
// ...
'modify_file' => true,
// ...
];
```
You can also set an oauth client ID and client secret. These values will be automatically prefilled in the authentication view in Swagger UI.
```php
// 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
```bash
composer test
```
## Linting
```bash
composer lint
```
### Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
### Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
## Credits
- [Günther Debrauwer](https://github.com/gdebrauwer)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.