Skip to content

Commit

Permalink
Merge pull request #11 from dommer1/custom-url
Browse files Browse the repository at this point in the history 
Support custom openapi url
  • Loading branch information
@gdebrauwer
gdebrauwer authored Feb 25, 2022
2 parents c37f589 + 513c6d8 commit e2667d8
Show file tree
Hide file tree
Showing 6 changed files with 95 additions and 25 deletions.
28 changes: 20 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ php artisan swagger-ui:install

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
```php
/**
* Register the Swagger UI gate.
*
Expand All @@ -44,7 +44,7 @@ protected function gate()
}
```

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 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.

```php
// in config/swagger-ui.php
Expand All @@ -60,8 +60,21 @@ return [
];
```

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.
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
Expand All @@ -84,7 +97,7 @@ return [

### Testing

``` bash
```bash
composer test
```

Expand All @@ -94,7 +107,6 @@ composer test
composer lint
```


### Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
Expand All @@ -109,8 +121,8 @@ If you discover any security related issues, please email gunther@nextapps.be in

## Credits

- [Günther Debrauwer](https://github.com/gdebrauwer)
- [All Contributors](../../contributors)
- [Günther Debrauwer](https://github.com/gdebrauwer)
- [All Contributors](../../contributors)

## License

Expand Down
16 changes: 15 additions & 1 deletion config/swagger-ui.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,26 @@
|--------------------------------------------------------------------------
|
| This is the location of the project's OpenAPI / Swagger JSON file. It's
| this file that will be used in Swagger UI.
| this file that will be used in Swagger UI. This can either be a local
| file or an url to a file.
|
*/

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

/*
|--------------------------------------------------------------------------
| Swagger UI - Modify File
|--------------------------------------------------------------------------
|
| If this option is enabled, then the file will be changed before it is
| used by Swagger UI. The server url and oauth urls will be changed to
| the base url of this Laravel application.
|
*/

'modify_file' => true,

/*
|--------------------------------------------------------------------------
| Swagger UI - OAuth Config
Expand Down
11 changes: 8 additions & 3 deletions src/Http/Controllers/OpenApiJsonController.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,20 +21,25 @@ public function __invoke() : JsonResponse
protected function getJson() : array
{
$path = config('swagger-ui.file');
$content = file_get_contents($path);

if (Str::endsWith($path, '.yaml')) {
if (! extension_loaded('yaml')) {
throw new RuntimeException('OpenAPI YAML file can not be parsed if the YAML extension is not loaded');
}

return yaml_parse_file($path);
return yaml_parse($content);
}

return json_decode(file_get_contents($path), true);
return json_decode($content, true);
}

protected function configureServer(array $json) : array
{
if (! config('swagger-ui.modify_file')) {
return $json;
}

$json['servers'] = [
['url' => config('app.url')],
];
Expand All @@ -44,7 +49,7 @@ protected function configureServer(array $json) : array

protected function configureOAuth(array $json) : array
{
if (empty($json['components']['securitySchemes'])) {
if (empty($json['components']['securitySchemes']) || ! config('swagger-ui.modify_file')) {
return $json;
}

Expand Down
43 changes: 41 additions & 2 deletions tests/OpenApiRouteTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,10 @@ public function openApiFileProvider() : array
* @test
* @dataProvider openApiFileProvider
*/
public function it_sets_server_to_current_app_url($openApiFile)
public function it_sets_server_to_current_app_url_if_modify_file_is_enabled($openApiFile)
{
config()->set('swagger-ui.file', $openApiFile);
config()->set('swagger-ui.modify_file', true);
config()->set('app.url', 'http://foo.bar');

$this->get('swagger/openapi.json')
Expand All @@ -50,9 +51,10 @@ public function it_sets_server_to_current_app_url($openApiFile)
* @test
* @dataProvider openApiFileProvider
*/
public function it_sets_oauth_urls_by_combining_configured_paths_with_current_app_url($openApiFile)
public function it_sets_oauth_urls_by_combining_configured_paths_with_current_app_url_if_modify_file_is_enabled($openApiFile)
{
config()->set('swagger-ui.file', $openApiFile);
config()->set('swagger-ui.modify_file', true);
config()->set('swagger-ui.oauth.token_path', 'this-is-token-path');
config()->set('swagger-ui.oauth.refresh_path', 'this-is-refresh-path');
config()->set('swagger-ui.oauth.authorization_path', 'this-is-authorization-path');
Expand All @@ -65,4 +67,41 @@ public function it_sets_oauth_urls_by_combining_configured_paths_with_current_ap
->assertJsonPath('components.securitySchemes.Foobar.flows.authorizationCode.tokenUrl', 'http://localhost/this-is-token-path')
->assertJsonPath('components.securitySchemes.Foobar.flows.authorizationCode.refreshUrl', 'http://localhost/this-is-refresh-path');
}

/**
* @test
* @dataProvider openApiFileProvider
*/
public function it_doesnt_sets_server_to_current_app_url_if_modify_file_is_disabled($openApiFile)
{
config()->set('swagger-ui.file', $openApiFile);
config()->set('swagger-ui.modify_file', false);
config()->set('app.url', 'http://foo.bar');

$this->get('swagger/openapi.json')
->assertStatus(200)
->assertJsonCount(1, 'servers')
->assertJsonPath('servers.0.url', 'http://localhost:3000');
}

/**
* @test
* @dataProvider openApiFileProvider
*/
public function it_doesnt_sets_oauth_urls_by_combining_configured_paths_with_current_app_url_if_modify_file_is_disabled($openApiFile)
{
config()->set('swagger-ui.file', $openApiFile);
config()->set('swagger-ui.modify_file', false);
config()->set('swagger-ui.oauth.token_path', 'this-is-token-path');
config()->set('swagger-ui.oauth.refresh_path', 'this-is-refresh-path');
config()->set('swagger-ui.oauth.authorization_path', 'this-is-authorization-path');

$this->get('swagger/openapi.json')
->assertStatus(200)
->assertJsonPath('components.securitySchemes.Foobar.flows.password.tokenUrl', 'http://localhost:3000/password/tokenUrl')
->assertJsonPath('components.securitySchemes.Foobar.flows.password.refreshUrl', 'http://localhost:3000/password/refreshUrl')
->assertJsonPath('components.securitySchemes.Foobar.flows.authorizationCode.authorizationUrl', 'http://localhost:3000/authorizationCode/authorizationUrl')
->assertJsonPath('components.securitySchemes.Foobar.flows.authorizationCode.tokenUrl', 'http://localhost:3000/authorizationCode/tokenUrl')
->assertJsonPath('components.securitySchemes.Foobar.flows.authorizationCode.refreshUrl', 'http://localhost:3000/authorizationCode/refreshUrl');
}
}
12 changes: 6 additions & 6 deletions tests/testfiles/openapi.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,19 +65,19 @@
"type": "oauth2",
"flows": {
"password": {
"tokenUrl": "http://localhost:3000/token",
"tokenUrl": "http://localhost:3000/password/tokenUrl",
"scopes": {},
"refreshUrl": "http://localhost:3000/refresh"
"refreshUrl": "http://localhost:3000/password/refreshUrl"
},
"authorizationCode": {
"authorizationUrl": "",
"tokenUrl": "",
"refreshUrl": "",
"authorizationUrl": "http://localhost:3000/authorizationCode/authorizationUrl",
"tokenUrl": "http://localhost:3000/authorizationCode/tokenUrl",
"refreshUrl": "http://localhost:3000/authorizationCode/refreshUrl",
"scopes": {}
}
},
"description": ""
}
}
}
}
}
10 changes: 5 additions & 5 deletions tests/testfiles/openapi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,12 @@ components:
type: oauth2
flows:
password:
tokenUrl: http://localhost:3000/token
tokenUrl: http://localhost:3000/password/tokenUrl
scopes: {}
refreshUrl: http://localhost:3000/refresh
refreshUrl: http://localhost:3000/password/refreshUrl
authorizationCode:
authorizationUrl: ''
tokenUrl: ''
refreshUrl: ''
authorizationUrl: http://localhost:3000/authorizationCode/authorizationUrl
tokenUrl: http://localhost:3000/authorizationCode/tokenUrl
refreshUrl: http://localhost:3000/authorizationCode/refreshUrl
scopes: {}
description: ''

0 comments on commit e2667d8

Please sign in to comment.