Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add swagger UI template blocks #918

Merged
merged 1 commit into from
Mar 3, 2023
Merged

Add swagger UI template blocks #918

merged 1 commit into from
Mar 3, 2023

Conversation

janlis-ff
Copy link
Contributor

@janlis-ff janlis-ff commented Jan 17, 2023 •
edited

First, on behalf of my several teams where we've been using drf_spectacular - a huge thank you to @tfranzel and all the other contributors for developing this project.

I noticed that the idea of template tags in swagger_ui.html is not new and has already been brought up in this pull request. I read the comments there, and would like to address @tfranzel 's issues raised there:

  • not that it matters much, but the block is not nested inside a extends which renders it non-functional afaik

    That is not correct. Defining e.g. {% block body %} in the template does not change the way the template is rendered, but instead it enables accessing and overriding this block in any template that extends the original template (see Django docs on template inheritance). What really matters is that instead of overriding the entire template it allows for extending it.

  • custom_scripts is below the js section. i could come up with a case, where it would also make sense to have it above. adding custom_scripts_before and custom_scripts_after seems kind of over the top.

    That is a perfectly valid point. What feels more robust to me is just enclosing the entire head and body tags in django template tags. This way, any content can be added at the beginning or at the end of these tags. I also think it's safe to say that any further customization should indeed be solved by completely overriding the template.

So here's my proposition to add two basic template tags to the swagger_ui.html template:

  • {% block head %} {% endblock %}
  • {% block body %} {% endblock %}

Which allows to:

  • add custom html at the end / beginning of <body>
  • add custom html at the end / beginning of <head>

For example:

<!-- myproject/templates/drf_spectacular/swagger_ui.html -->

{% extends "drf_spectacular/swagger_ui.html" %}

{% block body %}

    {{ block.super }}

    <script src='https://... '></script>
    <style> body, html { ... } </style>

{% endblock %}

And why is extending the template better than overriding it? Because in case anything changes in the original template, these changes won't be lost when extending the template, and they are when completely overriding it.
Also introducing a docs mention about it.

Looking forward to see what you think. Have a great day!

@tfranzel
Copy link
Owner

tfranzel commented Mar 3, 2023

Thank you @janlis-ff for your kind words and this PR.

That is not correct. Defining e.g. {% block body %} in the template does not change the way the template is rendered,

Yeah I know, I was too quick to dismiss that, not using templates that often.

This addresses my concern excellently. I like that this covers pre and post for both head and body. The ability to use block.super makes this much more useful.

@tfranzel tfranzel merged commit 43a4474 into tfranzel:master Mar 3, 2023
@tfranzel tfranzel mentioned this pull request Mar 3, 2023
Closed
@tfranzel tfranzel mentioned this pull request Apr 28, 2023
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
2 participants
@janlis-ff @tfranzel