TechQA.

How to integrate swagger-ui template with DRF and Django-Rest-framwork-Swagger?

3.4k views Asked by At

I am using Django & DRF to write REST APIs. Recently I integrated django-rest-framework-swagger to automatically populate the API docs.

Today, I came across swagger-ui template [https://github.com/jensoleg/swagger-ui] and now want to replace default swagger theme with this one.

What I tried already?

I copied all the contents of the dist directory into /venv/lib/python2.7/site-packages/rest_framework_swagger/static/rest_framework_swagger directory. But it didn't work (UI doesn't look good at all).

django django-rest-framework swagger-ui django-swagger
Original Q&A
1

There are 1 answers

1
Apoorv Kansal On

To customize django-rest-swagger ui template, all you need to do is include rest_framework_swagger/index.html in your root template directory. In my case, I had all of this under my own templates directory which was just the under the actual project folder.

This index.html file should look similar to this:

{% extends 'rest_framework_swagger/index.html' %}
{% load staticfiles %}
<!-- Your custom code -->

To see their already existing template:

{% load staticfiles %}
{% spaceless %}
<!DOCTYPE html>
<html>
    <head>
        <meta name="viewport" content="width=device-width initial-scale=1.0, maximum-scale=1.0, user-scalable=0">
            <title>{% block title %}Swagger UI{% endblock %}</title>
        {% block style %}
            <link href="//fonts.googleapis.com/css?family=Droid+Sans:400,700" rel="stylesheet" type="text/css"/>
            <link href="{% static 'rest_framework_swagger/css/highlight.default.css' %}" media="screen" rel="stylesheet" type="text/css"/>
            <link href="{% static 'rest_framework_swagger/css/atelier-dune.light.css' %}" media="screen" rel="stylesheet" type="text/css"/>
            <link href="{% static 'rest_framework_swagger/css/rest_framework_swagger.css' %}" media="screen" rel="stylesheet" type="text/css"/>
            <link href="{% static 'rest_framework_swagger/css/screen.css' %}" media="screen" rel="stylesheet" type="text/css"/>
        {% endblock %}
    </head>
    <body>
        {% block body %}
        {% block header %}
            <div id="header">
                <div class="swagger-ui-wrap">
                    {% block branding %}
                        <a id="logo" href="http://swagger.wordnik.com">swagger</a>
                    {% endblock %}
                    {% block api_selector %}
                        <form id="api_selector">
                            <div class="input icon-btn">
                                <img id="show-wordnik-dev-icon" src="{% static 'rest_framework_swagger/images/wordnik_api.png' %}" title="Show Wordnik Developer Apis">
                            </div>
                            <div class="input"><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
                            <div class="input"><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
                            <div class="input"><a id="explore" href="#">Explore</a></div>
                        </form>
                    {% endblock %}
                </div>
            </div>
        {% endblock %}

        {% block django_rest_swagger %}
            <div id="django-rest-swagger">
                <div class="swagger-ui-wrap">
                    <a href="https://github.com/marcgibbons/django-rest-swagger/">Django REST Swagger</a>
                </div>
            </div>
        {% endblock %}

        <div id="message-bar" class="swagger-ui-wrap"></div>
        <div id="swagger-ui-container" class="swagger-ui-wrap"></div>

        <script>
            window.static_url = "{{ STATIC_URL }}";
        </script>
        <script src="{% static 'rest_framework_swagger/lib/shred.bundle.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/jquery-1.8.0.min.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/jquery.slideto.min.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/jquery.wiggle.min.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/jquery.ba-bbq.min.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/jquery.cookie.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/handlebars-1.0.0.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/underscore-min.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/backbone-min.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/swagger.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/swagger-ui.min.js' %}" type="text/javascript"></script>
        <script src="{% static 'rest_framework_swagger/lib/highlight.8.0.pack.js' %}" type="text/javascript"></script>
        <script type="text/javascript">
            $(function () {
                window.swaggerUi = new SwaggerUi({
                    url: '{{ swagger_settings.discovery_url }}',
                    apiKey: '{{ swagger_settings.api_key }}',
                    dom_id: 'swagger-ui-container',
                    supportedSubmitMethods: {{ swagger_settings.enabled_methods }},
                    onComplete: function (swaggerApi, swaggerUi){
                        log('Loaded SwaggerUI')
                        $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
                    },
                    onFailure: function (data) {
                        log('Unable to Load SwaggerUI');
                    },
                    docExpansion: '{{ swagger_settings.doc_expansion }}',
                    csrfCookieName: {{ django_settings.CSRF_COOKIE_NAME }}
                });

                $('#input_apiKey').change(function () {
                    var key = $('#input_apiKey')[0].value;
                    log('key: ' + key);

                    if (key && key.trim() != '') {
                        console.log('added key ' + key);
                        window.authorizations.add('key', new ApiKeyAuthorization('Authorization', '{{ swagger_settings.token_type }} ' + key, 'header'));
                    }
                });

                {% if swagger_settings.api_key %}
                    window.authorizations.add('key', new ApiKeyAuthorization('Authorization', '{{ swagger_settings.token_type }} ' + '{{ swagger_settings.api_key }}', 'header'));
                {% endif %}

                {# Add version to Accept header, if AcceptHeaderVersioning is used. #}
                {% if swagger_settings.api_version and rest_framework_settings.DEFAULT_VERSIONING_CLASS == 'rest_framework.versioning.AcceptHeaderVersioning' %}
                    window.authorizations.add('version', {
                        apply: function(obj, authorizations) {
                            $.each(obj.headers, function(k, v) {
                                if (k.toLowerCase() === "accept") {
                                    if (v.indexOf('; version=') === -1) {
                                        obj.headers[k] += "; version={{ swagger_settings.api_version }}";
                                    }
                                    return false;  // break.
                                }
                            });
                            return true;
                        }
                    });
                {% endif %}

                window.swaggerUi.load();
            });
        </script>
        {% endblock %}
    </body>
</html>
{% endspaceless %}

This library code is found in rest_framework_swagger/base.html and their rest_framework_swagger/index.html simply looks like this:

{% extends 'rest_framework_swagger/base.html' %}

{# Override this template in your own templates directory to customize #}

NOTE: This solution works well with rest_framework_swagger 0.3.x. Their latest rest_framework_swagger (2.x), has a breaking change and I strongly recommend not to use it as you cannot do much customizations (eg. can't use YAML strings). I am using 0.3.x for my project and it's working absolutely fine.

Related Questions in DJANGO

Related Questions in DJANGO-REST-FRAMEWORK

Related Questions in SWAGGER-UI

Related Questions in DJANGO-SWAGGER

Popular Questions

Popular Tags

javascript python java c# php android html jquery c++ css ios sql mysql r reactjs node.js arrays c asp.net json python-3.x ruby-on-rails .net sql-server swift django angular objective-c pandas excel

Trending Questions