自定义

编辑此页

Swagger UI 的外观和感觉可以自定义。

覆盖 Twig 模板

如果您想自定义模板的某些部分，您可以创建自己的 Twig 模板。这允许更改 Swagger UI 配置、页面标题、页面页眉、添加额外的或替换现有的样式或脚本。

以下示例将向模板添加额外的脚本和自定义样式。只需创建一个文件 templates/bundles/NelmioApiDocBundle/SwaggerUi/index.html.twig。

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
        {# templates/bundles/NelmioApiDocBundle/SwaggerUi/index.html.twig #}

{#
    To avoid a "reached nested level" error an exclamation mark `!` has to be added
    See https://symfony.ac.cn/blog/new-in-symfony-3-4-improved-the-overriding-of-templates
#}
{% extends '@!NelmioApiDoc/SwaggerUi/index.html.twig' %}

{#
    Change Swagger UI configuration
    All parameters are explained on Swagger UI website:
    https://swagger.org.cn/docs/open-source-tools/swagger-ui/usage/configuration/
#}
{% block swagger_initialization %}
    <script type="text/javascript">
        window.onload = () => {
            loadSwaggerUI({
                defaultModelsExpandDepth: -1,
                deepLinking: true,
            });
        };
    </script>
{% endblock %}

{#
    Change Redocly configuration
    All parameters are explained on Redocly website:
    https://redocly.com/docs/redoc/config/
#}
{% block swagger_initialization %}
    <script type="text/javascript">
        window.onload = () => {
            loadRedocly({
                expandResponses: '200,201',
                hideDownloadButton: true,
            });
        };
    </script>
{% endblock %}

{# Import your own stylesheet #}
{% block stylesheets %}
    {{ parent() }}
    <link rel="stylesheet" href="{{ asset('css/custom-swagger-styles.css') }}">
{% endblock stylesheets %}

{# Import your own script #}
{% block javascripts %}
    {{ parent() }}
    <script type="text/javascript" src="{{ asset('js/custom-request-signer.js') }}"></script>
{% endblock javascripts %}
    

您可以查看原始模板，在 /templates/SwaggerUi/index.html.twig 中，查看哪些块可以被覆盖。

资源加载选项

`html_config` 设置允许您配置如何为 UI 加载资源。 `assets_mode` 选项支持三个值：`cdn`、`bundle` 和 `offline`。

        1
2
3
        nelmio_api_doc:
    html_config:
        assets_mode: 'cdn' # Other values: 'bundle', 'offline'
    

`assets_mode`

可以在 AssetsMode.php 中找到三个可能的值 - cdn: 从 jsDelivr 加载资源。 - bundle: 从 vendor 目录中的扩展包获取资源，包括更新。 - offline: 从本地 `assets` 目录加载资源，需要开发者手动更新它们。

这项工作，包括代码示例，根据 Creative Commons BY-SA 3.0 许可协议获得许可。

版本