From c771c684a8e6c2c95cb964a5a9235cbd607cc26b Mon Sep 17 00:00:00 2001 From: Markus Poerschke Date: Mon, 16 Jul 2018 09:45:18 +0200 Subject: [PATCH] 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 | 10 +++ Resources/doc/customization.rst | 38 ++++++++++ Resources/doc/faq.rst | 45 +++++++++++ Resources/doc/index.rst | 1 + Resources/public/style.css | 4 +- Resources/views/SwaggerUi/index.html.twig | 92 +++++++++++++---------- 6 files changed, 148 insertions(+), 42 deletions(-) create mode 100644 Resources/doc/customization.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 9564aa8..41334a3 100644 --- a/CHANGELOG.md +++ b/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) ------------------ diff --git a/Resources/doc/customization.rst b/Resources/doc/customization.rst new file mode 100644 index 0000000..f1c6135 --- /dev/null +++ b/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 `_. + +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() }} + + {% endblock stylesheets %} + + {% block javascripts %} + {{ parent() }} + + {% endblock javascripts %} + +You can have a look at the original template to see which blocks can be overridden. diff --git a/Resources/doc/faq.rst b/Resources/doc/faq.rst index aca9834..6d12540 100644 --- a/Resources/doc/faq.rst +++ b/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 %} + + {{ parent() }} + + {% endblock stylesheets %} diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst index a6cac48..51f175f 100644 --- a/Resources/doc/index.rst +++ b/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 diff --git a/Resources/public/style.css b/Resources/public/style.css index d966267..62c0927 100644 --- a/Resources/public/style.css +++ b/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; } diff --git a/Resources/views/SwaggerUi/index.html.twig b/Resources/views/SwaggerUi/index.html.twig index e806918..ec7efa6 100644 --- a/Resources/views/SwaggerUi/index.html.twig +++ b/Resources/views/SwaggerUi/index.html.twig @@ -8,54 +8,66 @@ file that was distributed with this source code. #} - - {{ swagger_data.spec.info.title }} - NelmioApiDocBundle + {% block meta %} + + {% endblock meta %} + {% block title %}{{ swagger_data.spec.info.title }}{% endblock title %} - - - + {% block stylesheets %} + + + {% endblock stylesheets %} - {# json_encode(65) is for JSON_UNESCAPED_SLASHES|JSON_HEX_TAG to avoid JS XSS #} - + {% block swagger_data %} + {# json_encode(65) is for JSON_UNESCAPED_SLASHES|JSON_HEX_TAG to avoid JS XSS #} + + {% endblock swagger_data %} - - - - - - - - - - - - - - - - - - - - - - - - - + {% block svg_icons %} + + + + + + + + + + + + + + + + + + + + + + + + + + {% endblock svg_icons %}
- + {% block header %} + + {% endblock header %}
-
+ {% block swagger_ui %} +
+ {% endblock %} -
- © 2017 Api-Platform -
+ {% block javascripts %} + + + {% endblock javascripts %} - - - + {% block swagger_initialization %} + + {% endblock swagger_initialization %}