آفلاین سازی swagger در django و ماژول drf-spectacular

1404/11/04 | 698 |
django

به صورت پیشفرض برای drf-yasg تمام asset ها بصورت آفلاین بارگزاری می شوند ولی برای drf-spectacular هنوز هم به cdn های خارجی برای این کار احتیاج است.

ستاپ اولیه پروژه

خوشبختانه طبق قواعد جنگو می توان یک ساختار نسبتا راحت را برای جاگیزینی این asset های آنلاین با محلی و یا با آروان انجام داد. از تنظیمات مربوط به templates و static های جنگو مطمئن بشید که به شکل زیر باشن.

# settings.py

# templates config

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / 'templates'],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]


# statics

STATIC_URL = "/static/"
MEDIA_URL = "/media/"

STATIC_ROOT = BASE_DIR / "staticfiles"
MEDIA_ROOT = BASE_DIR / "media"


STATICFILES_DIRS = [
    BASE_DIR / "static",
]

ستاپ مربوط به drf-spectacular

اول از نصب و ستاپ اولیه drf-spectacular مطمئن بشید.

# settings.py

# installled apps
INSTALLED_APPS = [    
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    
    ...
    "rest_framework",
    "drf_spectacular",
    ...
]


# spectacular settings (minimal)
SPECTACULAR_SETTINGS = {
    ...
    "TITLE": "Your Project API",
    ...
}

# drf configs
REST_FRAMEWORK = {
    ...
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
    ...
}

تنظیمات urls

...
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView


urlpatterns = [
	...
	path('schema/', SpectacularAPIView.as_view(), name='schema'),
	path('swagger/', SpectacularSwaggerView.as_view(url_name='schema'),
		 name='swagger-ui'),
	...   
]

وارد صفحه مربوط به Swagger شده و ببینید که چه css و یا js هایی لود نمی شوند.

https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui.css
https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui-bundle.js
https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui-standalone-preset.js

اما راه حل این موضوع سادس، طبق قواعد جنگو وقتی شما یک template را هم نام و هم دایرکتوری مربوط به ماژول در نظر میگیرید محتوایت آن باز نویسی شده و جایگزین می شود.

دانلود و قرار دادن css و js ها در پوشه static

  1. یک پوشه با نام drf_spectacular در دایرکتوری static بسازید
  2. هر 3 فایلی که لود نمی شد رو از آدرس ‏swagger-ui | ArvanCloud‏ دانلود کنید. (می تونین نسخه های min اون رو دانلود کنین)
  3. بعد از دانلود دایرکتوری مورد نظر و اسامی رو در نظر بگیرید تا در مرحله بعد استفاده کنیم.

در نهایت برای این بخش به این شکل خواهد بود:

ایجاد template لازم برای جایگزینی

برای اینکه به جای صفحه اصلی که asset های آنلاین را درخواست می کند یک صفحه دیگر جایگزین کنیم کافیست که در پوشه templates در پروژه و به خصوص داخل دایرکتوری drf_spectacular فایلی با اسم مشخص به نام swagger_ui.html ایجاد و محتویات زیر را جایگزین کنیم.

{% load static %}

<!DOCTYPE html>
<html>

<head>
    {% block head %}
    <title>{{ title|default:"Swagger" }}</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    {% if favicon_href %}
    <link rel="icon" href="{{ favicon_href }}">{% endif %}
    <link rel="stylesheet" href="{% static 'drf_spectacular/swagger-ui.min.css' %}">
    <style>
        html {
            box-sizing: border-box;
            overflow-y: scroll;
        }

        *,
        *:after,
        *:before {
            box-sizing: inherit;
        }

        body {
            background: #fafafa;
            margin: 0;
        }
    </style>
    {% endblock head %}
</head>

<body>
    {% block body %}
    <div id="swagger-ui"></div>
    <script src="{% static 'drf_spectacular/swagger-ui-bundle.min.js' %}"></script>
    <script src="{% static 'drf_spectacular/swagger-ui-standalone-preset.min.js' %}"></script>
    {% if script_url %}
    <script src="{{ script_url }}"></script>
    {% else %}
    <script>
        {% include template_name_js %}
    </script>
    {% endif %}
    {% endblock %}
</body>

</html>

باید به این شکل باشد:

قطعه کد بالا در اصل جایگزین ساختار اصلی خواهد شد و دیگر نیاز به تغییر چیزی نخواهد بود و حالا می تونین به صفحه swagger دسترسی پیدا کنین.

اشتراک گذاری:
برچسب:

ثبت دیدگاه

نکته: آدرس ایمیل شما منتشر نخواهد شد
0/600

دیدگاه کاربران (9)

avatar
حسین
24 , فروردین , 1405 - 08:51 قبل از ظهر

سلام استاد
متاسفانه django debug toolbar هم همین مشکل رو داره. احیانا asset های دیباگ تولبار رو ندارید اپلود کنید؟

avatar
علی بیگدلی
24 , فروردین , 1405 - 10:10 قبل از ظهر

این asset ها از داخل خود اپلیکیشن میاد cdn نیستن احتمالا باید یه بار collect static کنین

نکته: آدرس ایمیل شما منتشر نخواهد شد
0/600
avatar
Amir
12 , فروردین , 1405 - 17:18 بعد از ظهر

سلام
خیلی ممنون استاد بیگدلی

نکته: آدرس ایمیل شما منتشر نخواهد شد
0/600
avatar
صادق
04 , فروردین , 1405 - 02:47 قبل از ظهر

سلام
لطفا اگر مقدور هست نمونه‌ای از متن urls.py برای drf_spectacular رو هم بذارید
ممنون

avatar
علی بیگدلی
04 , فروردین , 1405 - 05:43 قبل از ظهر

اضافه شد

نکته: آدرس ایمیل شما منتشر نخواهد شد
0/600
avatar
امیرعباس
05 , بهمن , 1404 - 09:37 قبل از ظهر

سلام مهندس خسته نباشید میگم ممنون بابت نشر این پست و پست های مشابه توی این روزا خیلی کاربردی بودن. فقط ی سوال، موقع deploy پروژه دوباره باید تغیراتی که اعمال کردیم رو به حالت اولیه برگردونیم درسته؟ (مطمئن نیستم ولی) در این صورت لازمه ی برنچ جدا ایجاد کنیم که موقع دیپلوی تغیرات رو راحت تر اعمال کنیم؟

avatar
علی بیگدلی
05 , بهمن , 1404 - 09:48 قبل از ظهر

3 تا برنچ داشته باش یکی main که استیبل ترین نسخه باشه و یکی dev که توش توسعه بدی و یکی prod که برای پیاده سازیه
توی dev توسعه بده زمانی که نهایی شد بیارش روی main و بعد بیارش روی prod وقتی تست ها رو پاس می کنی
در نظر داشته باش که dockerfile مربوط به dev و prod متفاوت باید باشن مثلا یسری پکیج و کارا توی prod روی image مربوط به alpine ممکنه داشته باشی که توی dev نداری و یا هر چیز دیگه که برای prod لازمه

avatar
امیرعباس
05 , بهمن , 1404 - 10:55 قبل از ظهر

ممنون لطف کردید🙏

نکته: آدرس ایمیل شما منتشر نخواهد شد
0/600
avatar
علی بیگدلی

نویسنده

دوره های من در مکتبخونه

آخرین پست ها

انواع کش کردن در Django مبتنی بر API
انواع کش کردن در Django مبتنی بر API
  • django 1405/01/23
انواع کش کردن در Django مبتنی بر وبسایت
انواع کش کردن در Django مبتنی بر وبسایت
  • django 1405/01/23
جایگزینی mirror های ubuntu با آدرس های داخلی
جایگزینی mirror های ubuntu با آدرس های داخلی
  • tech 1405/01/09

آخرین دوره ها

بوت کمپ توسعه دهنده بک اند با پایتون (2026-1)
بوت کمپ توسعه دهنده بک اند پایتون (2026-1)
  • 10000000 33 دانشجو
آموزش Flask
آموزش Flask
  • 0 151 دانشجو
The Twelve-Factor App
The Twelve-Factor App
  • 0 112 دانشجو