Moar blocks

docs/custom_ui.rst

@@ -4,15 +4,8 @@ Customizing the web UI
 
 The web UI can be customized using the settings available in :ref:`swagger-ui-settings` and :ref:`redoc-ui-settings`.
 
-You can also extend one of the ``drf-yasg/swagger-ui.html`` or ``drf-yasg/redoc.html`` templates that are used for
+You can also extend one of the drf-yasg/swagger-ui.html_ or drf-yasg/redoc.html_ templates that are used for
-rendering. The customizable blocks are currently limited to:
+rendering. See the template source code (linked above) for a complete list of customizable blocks.
 
-{% block extra_styles %}
+.. _drf-yasg/swagger-ui.html: https://github.com/axnsan12/drf-yasg/blob/master/src/drf_yasg/templates/drf-yasg/swagger-ui.html
-  additional stylesheets
+.. _drf-yasg/redoc.html: https://github.com/axnsan12/drf-yasg/blob/master/src/drf_yasg/templates/drf-yasg/redoc.html
-
-{% block extra_scripts %}
-  additional scripts
-
-{% block user_context_message %}
-  *(swagger-ui session auth only)*
-  logged in user message

src/drf_yasg/static/drf-yasg/redoc-init.js

@@ -23,7 +23,7 @@ for (var p in redocSettings) {
     }
 }
 
-document.body.appendChild(redoc);
+document.body.replaceChild(redoc, document.getElementById('redoc-placeholder'));
 
 function hideEmptyVersion() {
     // 'span.api-info-version' is for redoc 1.x, 'div.api-info span' is for redoc 2-alpha

src/drf_yasg/static/drf-yasg/swagger-ui-init.js

@@ -1,12 +1,16 @@
 "use strict";
 var currentPath = window.location.protocol + "//" + window.location.host + window.location.pathname;
 var defaultSpecUrl = currentPath + '?format=openapi';
+
+// load the saved authorization state from localStorage; ImmutableJS is used for consistency with swagger-ui state
 var savedAuth = Immutable.fromJS({});
 try {
     savedAuth = Immutable.fromJS(JSON.parse(localStorage.getItem("drf-yasg-auth")) || {});
 } catch (e) {
     localStorage.removeItem("drf-yasg-auth");
 }
+
+// global SwaggerUI config object; can be changed directly or by hooking initSwaggerUiConfig
 var swaggerUiConfig = {
     url: defaultSpecUrl,
     dom_id: '#swagger-ui',
@@ -35,7 +39,7 @@ var swaggerUiConfig = {
     onComplete: function () {
         preauthorizeAny(savedAuth, window.ui);
         hookAuthActions(window.ui);
-    },
+    }
 };
 
 function patchSwaggerUi() {
@@ -62,29 +66,52 @@ function initSwaggerUi() {
         console.log("WARNING: skipping initSwaggerUi() because window.ui is already defined");
         return;
     }
+    if (document.querySelector('.auth-wrapper .authorize')) {
+        patchSwaggerUi();
+    }
+    else {
+        insertionQ('.auth-wrapper .authorize').every(patchSwaggerUi);
+    }
 
     var swaggerSettings = JSON.parse(document.getElementById('swagger-settings').innerHTML);
-    if (!('oauth2RedirectUrl' in swaggerSettings)) {
+
     var oauth2RedirectUrl = document.getElementById('oauth2-redirect-url');
+    if (oauth2RedirectUrl) {
+        if (!('oauth2RedirectUrl' in swaggerSettings)) {
             if (oauth2RedirectUrl) {
                 swaggerSettings['oauth2RedirectUrl'] = oauth2RedirectUrl.href;
-            oauth2RedirectUrl.parentNode.removeChild(oauth2RedirectUrl);
             }
         }
+        oauth2RedirectUrl.parentNode.removeChild(oauth2RedirectUrl);
+    }
 
     console.log('swaggerSettings', swaggerSettings);
+    var oauth2Config = JSON.parse(document.getElementById('oauth2-config').innerHTML);
+    console.log('oauth2Config', oauth2Config);
+
+    initSwaggerUiConfig(swaggerSettings, oauth2Config);
+    window.ui = SwaggerUIBundle(swaggerUiConfig);
+    window.ui.initOAuth(oauth2Config);
+}
+
+/**
+ * Initialize the global swaggerUiConfig with any given additional settings.
+ * @param swaggerSettings SWAGGER_SETTINGS from Django settings
+ * @param oauth2Settings OAUTH2_CONFIG from Django settings
+ */
+function initSwaggerUiConfig(swaggerSettings, oauth2Settings) {
     for (var p in swaggerSettings) {
         if (swaggerSettings.hasOwnProperty(p)) {
             swaggerUiConfig[p] = swaggerSettings[p];
         }
     }
-
-    var oauth2Config = JSON.parse(document.getElementById('oauth2-config').innerHTML);
-    console.log('oauth2Config', oauth2Config);
-    window.ui = SwaggerUIBundle(swaggerUiConfig);
-    window.ui.initOAuth(oauth2Config);
 }
 
+/**
+ * Call sui.preauthorize### according to the type of savedAuth.
+ * @param savedAuth auth object saved from authActions.authorize
+ * @param sui SwaggerUI or SwaggerUIBundle instance
+ */
 function preauthorizeAny(savedAuth, sui) {
     var schemeName = savedAuth.get("name"), schemeType = savedAuth.getIn(["schema", "type"]);
     if (schemeType === "basic" && schemeName) {
@@ -101,6 +128,11 @@ function preauthorizeAny(savedAuth, sui) {
     }
 }
 
+/**
+ * Manually apply auth headers from the given auth object.
+ * @param savedAuth auth object saved from authActions.authorize
+ * @param requestHeaders target headers
+ */
 function applyAuth(savedAuth, requestHeaders) {
     var schemeName = savedAuth.get("name"), schemeType = savedAuth.getIn(["schema", "type"]);
     if (schemeType === "basic" && schemeName) {
@@ -121,6 +153,11 @@ function applyAuth(savedAuth, requestHeaders) {
     }
 }
 
+/**
+ * Hook the authorize and logout actions of SwaggerUI.
+ * The hooks are used to persist authorization data and trigger schema refetch.
+ * @param sui SwaggerUI or SwaggerUIBundle instance
+ */
 function hookAuthActions(sui) {
     var originalAuthorize = sui.authActions.authorize;
     sui.authActions.authorize = function (authorization) {
@@ -144,13 +181,4 @@ function hookAuthActions(sui) {
     };
 }
 
-window.addEventListener('load', function () {
+window.addEventListener('load', initSwaggerUi);
-    initSwaggerUi();
-
-    if (document.querySelector('.auth-wrapper .authorize')) {
-        patchSwaggerUi();
-    }
-    else {
-        insertionQ('.auth-wrapper .authorize').every(patchSwaggerUi);
-    }
-});

src/drf_yasg/templates/drf-yasg/redoc.html

@@ -2,21 +2,45 @@
 <!DOCTYPE html>
 <html>
 <head>
-    <title>{{ title }}</title>
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{% block title %}{{ title }}{% endblock %}</title>
 
+    {% block extra_head %}
+        {# -- Add any extra HTML heads tags here - except scripts and styles -- #}
+    {% endblock %}
+
+    {% block favicon %}
+        {# -- Maybe replace the favicon -- #}
+        <link rel="icon" type="image/png" href="{% static 'drf-yasg/redoc/redoc-logo.png' %}"/>
+    {% endblock %}
+
+    {% block main_styles %}
         <link rel="stylesheet" type="text/css" href="{% static 'drf-yasg/style.css' %}"/>
+    {% endblock %}
     {% block extra_styles %}
         {# -- Add any additional CSS scripts here -- #}
     {% endblock %}
 </head>
 <body>
+
+{% block extra_body %}
+    {# -- Add any header/body markup here (rendered BEFORE the swagger-ui/redoc element) -- #}
+{% endblock %}
+
+<div id="redoc-placeholder"></div>
+
+{% block footer %}
+    {# -- Add any footer markup here (rendered AFTER the swagger-ui/redoc element) -- #}
+{% endblock %}
+
 <script id="redoc-settings" type="application/json">{{ redoc_settings | safe }}</script>
 
+{% block main_scripts %}
     <script src="{% static 'drf-yasg/insQ.min.js' %}"></script>
     <script src="{% static 'drf-yasg/redoc-init.js' %}"></script>
     <script src="{% static 'drf-yasg/redoc/redoc.min.js' %}"></script>
+{% endblock %}
 {% block extra_scripts %}
     {# -- Add any additional scripts here -- #}
 {% endblock %}

src/drf_yasg/templates/drf-yasg/swagger-ui.html

@@ -1,16 +1,23 @@
-<!-- HTML for static distribution bundle build -->
 {% load static %}
 <!DOCTYPE html>
-<html lang="en">
+<html>
 <head>
-    <meta charset="UTF-8">
+    <meta charset="utf-8"/>
-    <title>{{ title }}</title>
+    <title>{% block title %}{{ title }}{% endblock %}</title>
 
-    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700">
+    {% block extra_head %}
+        {# -- Add any extra HTML heads tags here - except scripts and styles -- #}
+    {% endblock %}
+
+    {% block favicon %}
+        {# -- Maybe replace the favicon -- #}
+        <link rel="icon" type="image/png" href="{% static 'drf-yasg/swagger-ui-dist/favicon-32x32.png' %}"/>
+    {% endblock %}
+
+    {% block main_styles %}
         <link rel="stylesheet" type="text/css" href="{% static 'drf-yasg/style.css' %}"/>
         <link rel="stylesheet" type="text/css" href="{% static 'drf-yasg/swagger-ui-dist/swagger-ui.css' %}">
-    <link rel="icon" type="image/png" href="{% static 'drf-yasg/swagger-ui-dist/favicon-32x32.png' %}" sizes="32x32"/>
+    {% endblock %}
-    <link rel="icon" type="image/png" href="{% static 'drf-yasg/swagger-ui-dist/favicon-16x16.png' %}" sizes="16x16"/>
     {% block extra_styles %}
         {# -- Add any additional CSS scripts here -- #}
     {% endblock %}
@@ -18,16 +25,26 @@
 
 <body class="swagger-body">
 
+{% block extra_body %}
+    {# -- Add any header/body markup here (rendered BEFORE the swagger-ui/redoc element) -- #}
+{% endblock %}
+
 <div id="swagger-ui"></div>
 
+{% block footer %}
+    {# -- Add any footer markup here (rendered AFTER the swagger-ui/redoc element) -- #}
+{% endblock %}
+
 <script id="swagger-settings" type="application/json">{{ swagger_settings | safe }}</script>
 <script id="oauth2-config" type="application/json">{{ oauth2_config | safe }}</script>
 
+{% block main_scripts %}
     <script src="{% static 'drf-yasg/swagger-ui-dist/swagger-ui-bundle.js' %}"></script>
     <script src="{% static 'drf-yasg/swagger-ui-dist/swagger-ui-standalone-preset.js' %}"></script>
     <script src="{% static 'drf-yasg/insQ.min.js' %}"></script>
     <script src="{% static 'drf-yasg/immutable.js' %}"></script>
     <script src="{% static 'drf-yasg/swagger-ui-init.js' %}"></script>
+{% endblock %}
 {% block extra_scripts %}
     {# -- Add any additional scripts here -- #}
 {% endblock %}
@@ -36,12 +53,14 @@
 
 {% if USE_SESSION_AUTH %}
     <div id="django-session-auth" class="hidden">
+        {% block session_auth_button %}
             {% csrf_token %}
 
             {% block user_context_message %}
                 {% if request.user.is_authenticated %}
                     <div class="hello">
-                    <span class="django-session">Django</span> <span class="label label-primary">{{ request.user }}</span>
+                        <span class="django-session">Django</span> <span
+                            class="label label-primary">{{ request.user }}</span>
                     </div>
                 {% endif %}
             {% endblock %}
@@ -63,6 +82,7 @@
                     </a>
                 </div>
             {% endif %}
+        {% endblock %}
     </div>
 {% endif %}
 </body>

update-ui.sh

@@ -7,7 +7,6 @@ wget https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js -O src/drf_yas
 
 cp -r node_modules/swagger-ui-dist src/drf_yasg/static/drf-yasg/
 pushd src/drf_yasg/static/drf-yasg/swagger-ui-dist/ >/dev/null
-rm -f swagger-ui.js
+rm -f package.json .npmignore README.md favicon-16x16.png
-rm -f package.json .npmignore README.md
+rm -f  swagger-ui.js index.html *.map
-rm -f index.html *.map
 popd >/dev/null