fix: web-schema documentation fixed (#1016)

zubhub_backend/.gitignore

@@ -11,3 +11,5 @@ cadvisor.htpasswd
 .ssl-data
 celerybeat-schedule
 celerybeat.pid
+venv/
+.idea/

zubhub_backend/compose/celery/requirements.txt

@@ -29,6 +29,8 @@ django-rest-swagger>=2.2.0
 django-summernote==0.8.11.6
 django-treebeard>=4.5.1
 djangorestframework>=3.11.2
+drf-spectacular>= 0.26.5
+drf-spectacular-sidecar>=2023.12.1
 factory-boy>=2.12.0
 Faker>=4.17.1
 flower>=0.9.5

zubhub_backend/compose/media/requirements.txt

@@ -18,6 +18,8 @@ django-capture-on-commit-callbacks>=1.2.0
 django-cors-headers>=3.1.1
 django-js-asset>=1.2.2
 djangorestframework>=3.11.2
+drf-spectacular>= 0.26.5
+drf-spectacular-sidecar>=2023.12.1
 factory-boy>=2.12.0
 Faker>=4.17.1
 ffmpy>=0.3.0

zubhub_backend/compose/web/requirements.txt

@@ -29,6 +29,8 @@ django-rest-swagger>=2.2.0
 django-summernote==0.8.11.6
 django-treebeard>=4.5.1
 djangorestframework>=3.11.2
+drf-spectacular>= 0.26.5
+drf-spectacular-sidecar>=2023.12.1
 factory-boy>=2.12.0
 Faker>=4.17.1
 flower>=0.9.5

zubhub_backend/zubhub/APIS/urls.py

@@ -1,9 +1,9 @@
 from django.urls import path, include
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
 from zubhub.views import (UploadFileAPIView, DeleteFileAPIView,
                           HeroAPIView, HelpAPIView, ChallengeAPIView, PrivacyAPIView, FAQAPIView, AmbassadorsAPIView,
                           SigGenAPIView, UploadFileToLocalAPIView, ThemeAPIView)
 
-
 urlpatterns = [
     path('rest-auth/', include('rest_auth.urls')),
     path('rest-auth/registration/', include('rest_auth.registration.urls')),
@@ -24,5 +24,7 @@
     path('challenge/', ChallengeAPIView.as_view(), name="challenge"),
     path('signature/', SigGenAPIView,
          name="signature_generator_api"),
-     path('theme/', ThemeAPIView.as_view(), name="theme"),
+    path('theme/', ThemeAPIView.as_view(), name="theme"),
+    path('schema/', SpectacularAPIView.as_view(), name='schema'),
+    path('schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
 ]

zubhub_backend/zubhub/zubhub/settings.py

@@ -10,8 +10,8 @@
 https://docs.djangoproject.com/en/2.2/ref/settings/
 """
 
-import socket
 import os
+import socket
 
 # Build paths inside the project like this: os.path.join(BASE_DIR, ...)
 BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
@@ -70,17 +70,17 @@
 SECRET_KEY = os.environ.get('SECRET_KEY')
 
 ALLOWED_HOSTS = ['127.0.0.1', FRONTEND_HOST, "www." +
-                 FRONTEND_HOST, BACKEND_HOST, "www."+BACKEND_HOST, "web"]
+                 FRONTEND_HOST, BACKEND_HOST, "www." + BACKEND_HOST, "web"]
 # ALLOWED_HOSTS = ['*']
 
 # CORS_ORIGIN_ALLOW_ALL = True
 
 CORS_ORIGIN_WHITELIST = (
-    DEFAULT_FRONTEND_PROTOCOL+"://"+DEFAULT_FRONTEND_DOMAIN,
-    DEFAULT_BACKEND_PROTOCOL+"://"+DEFAULT_BACKEND_DOMAIN,
-    DEFAULT_FRONTEND_PROTOCOL+"://www."+DEFAULT_FRONTEND_DOMAIN,
-    DEFAULT_BACKEND_PROTOCOL+"://www."+DEFAULT_BACKEND_DOMAIN,
-    DEFAULT_MEDIA_SERVER_PROTOCOL+"://"+DEFAULT_MEDIA_SERVER_DOMAIN
+    DEFAULT_FRONTEND_PROTOCOL + "://" + DEFAULT_FRONTEND_DOMAIN,
+    DEFAULT_BACKEND_PROTOCOL + "://" + DEFAULT_BACKEND_DOMAIN,
+    DEFAULT_FRONTEND_PROTOCOL + "://www." + DEFAULT_FRONTEND_DOMAIN,
+    DEFAULT_BACKEND_PROTOCOL + "://www." + DEFAULT_BACKEND_DOMAIN,
+    DEFAULT_MEDIA_SERVER_PROTOCOL + "://" + DEFAULT_MEDIA_SERVER_DOMAIN
 )
 
 # Application definition
@@ -116,13 +116,15 @@
     'notifications',
     'activitylog',
     'activities',
+    'drf_spectacular',
+    'drf_spectacular_sidecar',
 ]
 
 # askimet
 AKISMET_API_KEY = os.environ.get("AKISMET_API_KEY")
 
-
 REST_FRAMEWORK = {
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
     'DEFAULT_PERMISSION_CLASSES': [
         'rest_framework.permissions.AllowAny',
     ],
@@ -153,7 +155,6 @@
 
 DEFAULT_AUTO_FIELD = 'django.db.models.AutoField'
 
-
 # django-allauth config
 LOGIN_REDIRECT_URL = '/api'
 ACCOUNT_LOGOUT_REDIRECT = '/api'
@@ -171,10 +172,8 @@
 # ACCOUNT_EMAIL_REQUIRED = True
 ACCOUNT_UNIQUE_EMAIL = True
 
-
 CRISPY_TEMPLATE_PACK = 'bootstrap4'
 
-
 MIDDLEWARE = [
     'django.middleware.security.SecurityMiddleware',
     'django.contrib.sessions.middleware.SessionMiddleware',
@@ -210,7 +209,6 @@
 
 WSGI_APPLICATION = 'zubhub.wsgi.application'
 
-
 # Database
 # https://docs.djangoproject.com/en/2.2/ref/settings/#databases
 
@@ -232,7 +230,6 @@
     }
 }
 
-
 # Password validation
 # https://docs.djangoproject.com/en/2.2/ref/settings/#auth-password-validators
 
@@ -251,7 +248,6 @@
     },
 ]
 
-
 # Internationalization
 # https://docs.djangoproject.com/en/2.2/topics/i18n/
 
@@ -267,7 +263,6 @@
 
 LOCALE_PATHS = [os.path.join(BASE_DIR, 'locale')]
 
-
 # Static files (CSS, JavaScript, Images)
 # https://docs.djangoproject.com/en/2.2/howto/static-files/
 
@@ -292,7 +287,6 @@
 CELERY_BROKER_URL = os.environ.get("CELERY_BROKER")
 CELERY_RESULT_BACKEND = os.environ.get("CELERY_BACKEND")
 
-
 ################################################################################
 # How to send email in Django project with Celery
 ################################################################################
@@ -308,7 +302,6 @@
 EMAIL_PORT = 465
 EMAIL_USE_SSL = True
 
-
 DEFAULT_FROM_PHONE = os.environ.get("DEFAULT_FROM_PHONE")
 DEFAULT_WHATSAPP_FROM_PHONE = os.environ.get("DEFAULT_WHATSAPP_FROM_PHONE")
 TWILIO_ACCOUNT_SID = os.environ.get("TWILIO_ACCOUNT_SID")
@@ -322,7 +315,6 @@
     'ignore_result': False,
 }
 
-
 SUMMERNOTE_CONFIG = {
 
     # You can put custom Summernote settings
@@ -349,9 +341,19 @@
     "js": ("/static/js/summernote_plugin.js",)
 }
 
-
 # for auto-generating the database schema
 GRAPH_MODELS = {
     'all_applications': True,
     'group_models': True,
 }
+
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'ZubHub API',
+    'DESCRIPTION': 'API for ZubHub',
+    'VERSION': '0.0.1',
+    'SERVE_INCLUDE_SCHEMA': False,
+    'PREPROCESSING_HOOKS': [
+        'zubhub.utils.preprocess_schema',
+    ],
+    'theme': {},
+}

zubhub_backend/zubhub/zubhub/urls.py

@@ -15,9 +15,10 @@
 """
 from django.conf import settings
 from django.contrib import admin
-from django.urls import path, include
+from django.urls import path, include, re_path
 from django.views.generic import TemplateView
 from django.conf.urls.static import static
+from drf_spectacular.views import SpectacularRedocView
 
 
 schema_url_patterns = []
@@ -28,6 +29,7 @@
     path('api-auth/', include('rest_framework.urls')),
     path('summernote/', include('django_summernote.urls')),
     path('api/', include('APIS.urls')),
+    re_path(r'^$', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
 ]
 
 

zubhub_backend/zubhub/zubhub/utils.py

@@ -11,6 +11,8 @@
 from django.utils.deconstruct import deconstructible
 from django.conf import settings
 from projects.tasks import delete_file_task
+from os import path
+from base64 import b64encode
 
 
 def get_hash(string):
@@ -99,7 +101,7 @@ def get_image_paths(html):
     e.g. ["image.jpg", "image2.png", "image3.jpg"]
     """
     import re
-    
+
     try:
         paths =  re.findall(r'<img[^<>]+src=["\']./([^"\'<>]+\.(?:gif|png|jpe?g))["\']', html, re.I)
         return paths
@@ -109,11 +111,8 @@ def get_image_paths(html):
 def images_to_base64(paths, html):
     """ Replace all image names in html image tag with the base64 string of corresponding image """
 
-    from os import path
-    from base64 import b64encode
-
     try:
-        for image in paths: # path contains image file names e.g. one.jpg, two.png 
+        for image in paths: # path contains image file names e.g. one.jpg, two.png
             image_path = path.join(settings.BASE_DIR, 'docs', 'docs', image) # get image full path
             with open(image_path, "rb") as file:
                 base64_data = b64encode(file.read())
@@ -123,7 +122,7 @@ def images_to_base64(paths, html):
         return html
 #==================================================================================
 
-    
+
 @deconstructible
 class MediaStorage(Storage):
     def __eq__(self, other):
@@ -151,3 +150,18 @@ def get_available_name(self, name, max_length):
     def url(self, name):
         return name
 
+
+def preprocess_schema(endpoints):
+    """
+    Replace all image names in html image tag with the base64 string of corresponding image
+    """
+    filtered = []
+    for (p, path_regex, method, callback) in endpoints:
+        if (
+            p.startswith("/api/") or
+            p.startswith("/rest-auth/") or
+            p.startswith("/summernote/") or
+            p.startswith("/api-auth/")
+        ):
+            filtered.append((p, path_regex, method, callback))
+    return filtered

zubhub_backend/zubhub/zubhub/views.py

@@ -12,6 +12,8 @@
 from rest_framework.generics import ListAPIView, RetrieveAPIView
 from rest_framework.permissions import AllowAny
 from rest_framework.decorators import api_view, permission_classes, throttle_classes
+from rest_framework.schemas.openapi import SchemaGenerator
+from .urls import schema_url_patterns
 from django.utils.text import slugify
 from django.conf import settings
 from django.utils.translation import ugettext_lazy as _
@@ -324,9 +326,6 @@ def WebSchemaAPIView(request):
     Returns Web API schema.
     """
 
-    from rest_framework.schemas.openapi import SchemaGenerator
-    from .urls import schema_url_patterns
-
     generator = SchemaGenerator(title='Zubhub Web Server API', patterns=schema_url_patterns)
 
     return Response(generator.get_schema())