mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-02-02 15:51:48 +03:00
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
This commit is contained in:
Markus Poerschke
Guilhem N
parent
ab005c4129
commit
c771c684a8
10
CHANGELOG.md
10
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)
|
||||
------------------
|
||||
|
||||
|
||||
38
Resources/doc/customization.rst
Normal file
38
Resources/doc/customization.rst
Normal file
@ -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.
|
||||
@ -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 %}
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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;
|
||||
}
|
||||
|
||||
@ -8,54 +8,66 @@ file that was distributed with this source code. #}
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>{{ swagger_data.spec.info.title }} - NelmioApiDocBundle</title>
|
||||
{% block meta %}
|
||||
<meta charset="UTF-8">
|
||||
{% 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">
|
||||
<link rel="stylesheet" href="{{ asset('bundles/nelmioapidoc/swagger-ui/swagger-ui.css') }}">
|
||||
<link rel="stylesheet" href="{{ asset('bundles/nelmioapidoc/style.css') }}">
|
||||
{% 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 %}
|
||||
|
||||
{# 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>
|
||||
{% 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>
|
||||
<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">
|
||||
<path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 20 20" id="locked">
|
||||
<path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 20 20" id="close">
|
||||
<path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 20 20" id="large-arrow">
|
||||
<path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 20 20" id="large-arrow-down">
|
||||
<path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 24 24" id="jump-to">
|
||||
<path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 24 24" id="expand">
|
||||
<path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"></path>
|
||||
</symbol>
|
||||
</defs>
|
||||
</svg>
|
||||
{% 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">
|
||||
<path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 20 20" id="locked">
|
||||
<path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 20 20" id="close">
|
||||
<path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 20 20" id="large-arrow">
|
||||
<path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 20 20" id="large-arrow-down">
|
||||
<path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 24 24" id="jump-to">
|
||||
<path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"></path>
|
||||
</symbol>
|
||||
<symbol viewBox="0 0 24 24" id="expand">
|
||||
<path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"></path>
|
||||
</symbol>
|
||||
</defs>
|
||||
</svg>
|
||||
{% endblock svg_icons %}
|
||||
<header>
|
||||
<a id="logo" href="https://github.com/nelmio/NelmioApiDocBundle"><img src="{{ asset('bundles/nelmioapidoc/logo.png') }}" alt="NelmioApiDocBundle"></a>
|
||||
{% block header %}
|
||||
<a id="logo" href="https://github.com/nelmio/NelmioApiDocBundle"><img src="{{ asset('bundles/nelmioapidoc/logo.png') }}" alt="NelmioApiDocBundle"></a>
|
||||
{% endblock header %}
|
||||
</header>
|
||||
|
||||
<div id="swagger-ui" class="api-platform"></div>
|
||||
{% block swagger_ui %}
|
||||
<div id="swagger-ui" class="api-platform"></div>
|
||||
{% endblock %}
|
||||
|
||||
<div class="swagger-ui-wrap" style="margin-top: 20px; margin-bottom: 20px;">
|
||||
© 2017 <a href="https://api-platform.com">Api-Platform</a>
|
||||
</div>
|
||||
{% block javascripts %}
|
||||
<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 %}
|
||||
|
||||
<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>
|
||||
<script src="{{ asset('bundles/nelmioapidoc/init-swagger-ui.js') }}"></script>
|
||||
{% block swagger_initialization %}
|
||||
<script src="{{ asset('bundles/nelmioapidoc/init-swagger-ui.js') }}"></script>
|
||||
{% endblock swagger_initialization %}
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user