From 71dee6eb451796eeb131b73de7ec1e8c0af3547f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristi=20V=C3=AEjdea?= Date: Sun, 4 Feb 2018 14:36:54 +0200 Subject: [PATCH] Add OAuth2 client configuration for swagger-ui (#57) --- docs/changelog.rst | 1 + docs/security.rst | 16 ++++++++++++++++ docs/settings.rst | 19 +++++++++++++++++++ src/drf_yasg/app_settings.py | 2 ++ src/drf_yasg/renderers.py | 7 +++++++ .../static/drf-yasg/swagger-ui-init.js | 5 +++++ .../templates/drf-yasg/swagger-ui.html | 1 + 7 files changed, 51 insertions(+) diff --git a/docs/changelog.rst b/docs/changelog.rst index 7cec2a8..787c878 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -6,6 +6,7 @@ Changelog **1.4.0** ********* +- **ADDED:** added settings for OAuth2 client configuration in ``swagger-ui`` (:issue:`53`) - **IMPROVED:** updated ``swagger-ui`` to version 3.9.3 ********* diff --git a/docs/security.rst b/docs/security.rst index 4147ce9..e172a69 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -47,3 +47,19 @@ Operation-level overrides can be added using the ``security`` parameter of :ref:`@swagger_auto_schema `. +------------------------------- +``swagger-ui`` as OAuth2 client +------------------------------- + +It is possible to configure ``swagger-ui`` to authenticate against your (or a third party) OAuth2 service when sending +"Try it out" requests. This client-side configuration does not remove the requirement of a spec-side +:ref:`security definiiton `, but merely allows you to test OAuth2 APIs using +``swagger-ui`` as a client. + +**DISCLAIMER**: this setup is very poorly tested as I do not currently implement OAuth in any of my projects. All +contributions relating to documentation, bugs, mistakes or anything else are welcome as an issue or pull request. The +settings described below were added as a result of discussion in issue :issue:`53`. + +The settings of interest can be found on the :ref:`settings page `. Configuration options are similar +to most OAuth client setups like web or mobile applications. Reading the relevant ``swagger-ui`` docmentation linked +will also probably help. diff --git a/docs/settings.rst b/docs/settings.rst index 73f28e1..705dcf4 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -253,6 +253,25 @@ Controls how many levels are expaned by default when showing nested models. **Default**: :python:`3` |br| *Maps to parameter*: ``defaultModelExpandDepth`` +.. _oauth2-settings: + +OAUTH2_REDIRECT_URL +------------------- + +Used when OAuth2 authenitcation of API requests via swagger-ui is desired. + +**Default**: :python:`None` |br| +*Maps to parameter*: ``oauth2RedirectUrl`` + +OAUTH2_CONFIG +------------- + +Used when OAuth2 authenitcation of API requests via swagger-ui is desired. Provides OAuth2 configuration parameters +to the ``SwaggerUIBundle#initOAuth`` method, and must be a dictionary. See +`OAuth2 configuration `_. + +**Default**: :python:`{}` + ****************** ``REDOC_SETTINGS`` ****************** diff --git a/src/drf_yasg/app_settings.py b/src/drf_yasg/app_settings.py index dc6cb9a..7978959 100644 --- a/src/drf_yasg/app_settings.py +++ b/src/drf_yasg/app_settings.py @@ -43,6 +43,8 @@ SWAGGER_DEFAULTS = { 'SHOW_EXTENSIONS': True, 'DEFAULT_MODEL_RENDERING': 'model', 'DEFAULT_MODEL_DEPTH': 3, + 'OAUTH2_REDIRECT_URL': None, + 'OAUTH2_CONFIG': {}, } REDOC_DEFAULTS = { diff --git a/src/drf_yasg/renderers.py b/src/drf_yasg/renderers.py index 9f5b5ab..def9ca4 100644 --- a/src/drf_yasg/renderers.py +++ b/src/drf_yasg/renderers.py @@ -63,6 +63,7 @@ class _UIRenderer(BaseRenderer): renderer_context['version'] = swagger.info.version renderer_context['swagger_settings'] = json.dumps(self.get_swagger_ui_settings()) renderer_context['redoc_settings'] = json.dumps(self.get_redoc_settings()) + renderer_context['oauth2_config'] = json.dumps(self.get_oauth2_config()) renderer_context['USE_SESSION_AUTH'] = swagger_settings.USE_SESSION_AUTH renderer_context.update(self.get_auth_urls()) @@ -85,6 +86,7 @@ class _UIRenderer(BaseRenderer): 'defaultModelRendering': swagger_settings.DEFAULT_MODEL_RENDERING, 'defaultModelExpandDepth': swagger_settings.DEFAULT_MODEL_DEPTH, 'defaultModelsExpandDepth': swagger_settings.DEFAULT_MODEL_DEPTH, + 'oauth2RedirectUrl': swagger_settings.OAUTH2_REDIRECT_URL, } data = {k: v for k, v in data.items() if v is not None} if swagger_settings.VALIDATOR_URL != '': @@ -102,6 +104,11 @@ class _UIRenderer(BaseRenderer): return data + def get_oauth2_config(self): + data = swagger_settings.OAUTH2_CONFIG + assert isinstance(data, dict), "OAUTH2_CONFIG must be a dict" + return data + class SwaggerUIRenderer(_UIRenderer): """Renders a swagger-ui web interface for schema browisng. diff --git a/src/drf_yasg/static/drf-yasg/swagger-ui-init.js b/src/drf_yasg/static/drf-yasg/swagger-ui-init.js index acf28a6..5a83468 100644 --- a/src/drf_yasg/static/drf-yasg/swagger-ui-init.js +++ b/src/drf_yasg/static/drf-yasg/swagger-ui-init.js @@ -49,6 +49,7 @@ function initSwaggerUi() { }; var swaggerSettings = JSON.parse(document.getElementById('swagger-settings').innerHTML); + console.log(swaggerSettings); for (var p in swaggerSettings) { if (swaggerSettings.hasOwnProperty(p)) { @@ -56,6 +57,10 @@ function initSwaggerUi() { } } window.ui = SwaggerUIBundle(swaggerConfig); + + var oauth2Config = JSON.parse(document.getElementById('oauth2-config').innerHTML); + console.log(oauth2Config); + window.ui.initOAuth(oauth2Config); } window.onload = function () { diff --git a/src/drf_yasg/templates/drf-yasg/swagger-ui.html b/src/drf_yasg/templates/drf-yasg/swagger-ui.html index 6e70dae..b99327b 100644 --- a/src/drf_yasg/templates/drf-yasg/swagger-ui.html +++ b/src/drf_yasg/templates/drf-yasg/swagger-ui.html @@ -60,6 +60,7 @@ +