Customizable template and remove Google Fonts (#1357)

* Allow to override certain parts of the template

* Twig template can be defined via config
* Blocks can be used to override/extend only parts of the template

* Fix spelling in documentation

* Fix extension configuration tree

* Fix unit tests by making constructor argument optional

* Add fonts block and split swagger initialization into own block

* Fix code style

* Remove Google fonts, remove configuration and add changelog entry

* Remove template argument from service definition

* Add correct path for overriding template

* Move re-add of Google Fonts to FAQ section in documentation.

* Remove unused class import

CHANGELOG.md

@@ -1,6 +1,16 @@
 CHANGELOG
 =========
 
+3.3.0 (unreleased)
+------------------
+
+* Usage of Google Fonts was removed. System fonts `serif` / `sans` will be used instead. 
+  This can lead to a different look on different operating systems.
+  You can [re-add Google Fonts again manually by overriding the template](https://symfony.com/doc/current/bundles/NelmioApiDocBundle/faq.html#re-add-google-fonts).
+
+* The Twig template for the Swagger UI now contains blocks to make it easier to overwrite certain parts.
+  See the [official documentation](https://symfony.com/doc/current/bundles/NelmioApiDocBundle/customization.html) how to do this.
+
 3.2.0 (2018-03-24)
 ------------------
 

Resources/doc/customization.rst

@@ -0,0 +1,38 @@
+Customization
+=============
+
+The look and feel of the Swagger UI can be customized.
+
+
+Overwrite Twig Template
+-----------------------
+
+If you want to customize parts of the template, you can create your own Twig template.
+This allows to change the title, the header, add additional or replace existing styles or scripts.
+
+Take a look at the Twig documentation `how to extend templates <https://twig.symfony.com/doc/2.x/tags/extends.html>`_.
+
+The following example will add additional scripts and a custom style to the template.
+Just create a file ``templates/bundles/NelmioApiDocBundle/SwaggerUI/index.html.twig``.
+
+.. code-block:: twig
+
+    {# templates/bundles/NelmioApiDocBundle/views/SwaggerUI/index.html.twig #}
+
+    {#
+        To avoid a "reached nested level" error an exclamation mark `!` has to be added
+        See https://symfony.com/blog/new-in-symfony-3-4-improved-the-overriding-of-templates
+    #}
+    {% extends '@!NelmioApiDoc/SwaggerUi/index.html.twig' %}
+
+    {% block stylesheets %}
+        {{ parent() }}
+        <link rel="stylesheet" href="{{ asset('css/custom-swagger-styles.css') }}">
+    {% endblock stylesheets %}
+
+    {% block javascripts %}
+        {{ parent() }}
+        <script type="text/javascript" src="{{ asset('js/custom-request-signer.js') }}"></script>
+    {% endblock javascripts %}
+
+You can have a look at the original template to see which blocks can be overridden.

Resources/doc/faq.rst

@@ -127,3 +127,48 @@ A: The assets normally are installed by composer if any command event (usually `
 
     $ bin/console assets:install --symlink
 
+Re-add Google Fonts
+-------------------
+
+Q: How can I re-add Google Fonts?
+
+A: Create a override template file inside your project and add the following content:
+
+.. code-block:: twig
+
+    {# templates/bundles/NelmioApiDocBundle/SwaggerUI/index.html.twig #}
+
+    {% block stylesheets %}
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700">
+        {{ parent() }}
+        <style type="text/css" rel="stylesheet">
+            #formats {
+                font-family: Open Sans,sans-serif;
+            }
+
+            .swagger-ui .opblock-tag,
+            .swagger-ui .opblock .opblock-section-header label,
+            .swagger-ui .opblock .opblock-section-header h4,
+            .swagger-ui .opblock .opblock-summary-method,
+            .swagger-ui .tab li,
+            .swagger-ui .scheme-container .schemes>label,
+            .swagger-ui .loading-container .loading:after,
+            .swagger-ui .btn,
+            .swagger-ui .btn.cancel,
+            .swagger-ui select,
+            .swagger-ui label,
+            .swagger-ui .dialog-ux .modal-ux-content h4,
+            .swagger-ui .dialog-ux .modal-ux-header h3,
+            .swagger-ui section.models h4,
+            .swagger-ui section.models h5,
+            .swagger-ui .model-title,
+            .swagger-ui .parameter__name,
+            .swagger-ui .topbar a,
+            .swagger-ui .topbar .download-url-wrapper .download-url-button,
+            .swagger-ui .info .title small pre,
+            .swagger-ui .scopes h2,
+            .swagger-ui .errors-wrapper hgroup h4 {
+                font-family: Open Sans,sans-serif!important;
+            }
+        </style>
+    {% endblock stylesheets %}

Resources/doc/index.rst

@@ -303,6 +303,7 @@ If you need more complex features, take a look at:
 
     areas
     alternative_names
+    customization
     faq
 
 .. _`Symfony PropertyInfo component`: https://symfony.com/doc/current/components/property_info.html

Resources/public/style.css

@@ -171,7 +171,7 @@ header #logo img {
 
 #formats {
   text-align:right;
-  font-family: Open Sans,sans-serif;
+  font-family: sans-serif;
   width: 100%;
   max-width: 1460px;
   padding: 0px 60px;
@@ -287,5 +287,5 @@ text-align:center;
 .swagger-ui .info .title small pre,
 .swagger-ui .scopes h2,
 .swagger-ui .errors-wrapper hgroup h4 {
-  font-family: Open Sans,sans-serif!important;
+  font-family: sans-serif !important;
 }

Resources/views/SwaggerUi/index.html.twig

@@ -8,17 +8,23 @@ file that was distributed with this source code. #}
 <!DOCTYPE html>
 <html>
 <head>
+    {% block meta %}
         <meta charset="UTF-8">
-    <title>{{ swagger_data.spec.info.title }} - NelmioApiDocBundle</title>
+    {% endblock meta %}
+    <title>{% block title %}{{ swagger_data.spec.info.title }}{% endblock title %}</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 stylesheets %}
         <link rel="stylesheet" href="{{ asset('bundles/nelmioapidoc/swagger-ui/swagger-ui.css') }}">
         <link rel="stylesheet" href="{{ asset('bundles/nelmioapidoc/style.css') }}">
+    {% endblock stylesheets %}
 
+    {% block swagger_data %}
         {# json_encode(65) is for JSON_UNESCAPED_SLASHES|JSON_HEX_TAG to avoid JS XSS #}
         <script id="swagger-data" type="application/json">{{ swagger_data|json_encode(65)|raw }}</script>
+    {% endblock swagger_data %}
 </head>
 <body>
+    {% block svg_icons %}
         <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="position:absolute;width:0;height:0">
             <defs>
                 <symbol viewBox="0 0 20 20" id="unlocked">
@@ -44,18 +50,24 @@ file that was distributed with this source code. #}
                 </symbol>
             </defs>
         </svg>
+    {% endblock svg_icons %}
     <header>
+        {% block header %}
             <a id="logo" href="https://github.com/nelmio/NelmioApiDocBundle"><img src="{{ asset('bundles/nelmioapidoc/logo.png') }}" alt="NelmioApiDocBundle"></a>
+        {% endblock header %}
     </header>
 
+    {% block swagger_ui %}
         <div id="swagger-ui" class="api-platform"></div>
+    {% endblock %}
 
-    <div class="swagger-ui-wrap" style="margin-top: 20px; margin-bottom: 20px;">
+    {% block javascripts %}
-        &copy; 2017 <a href="https://api-platform.com">Api-Platform</a>
-    </div>
-
         <script src="{{ asset('bundles/nelmioapidoc/swagger-ui/swagger-ui-bundle.js') }}"></script>
         <script src="{{ asset('bundles/nelmioapidoc/swagger-ui/swagger-ui-standalone-preset.js') }}"></script>
+    {% endblock javascripts %}
+
+    {% block swagger_initialization %}
         <script src="{{ asset('bundles/nelmioapidoc/init-swagger-ui.js') }}"></script>
+    {% endblock swagger_initialization %}
 </body>
 </html>