feat: add Django REST Framework support with custom exception handling and CORS configuration

Author: Mangolja

django/cookiecutter.json

@@ -13,5 +13,6 @@
   "username_type": [
     "email",
     "username"
-  ]
+  ],
+  "use_drf": "y"
 }

django/hooks/post_gen_project.py

@@ -0,0 +1,24 @@
+import sys
+from pathlib import Path
+
+project_slug = "{{ cookiecutter.project_slug }}"
+project_path = Path(project_slug)
+use_drf = "{{ cookiecutter.use_drf }}" == "y"
+
+def _remove_file(file_path: Path) -> None:
+    """Remove a file if it exists."""
+    file_path.unlink(missing_ok=True)
+
+
+def handle_drf():
+    if use_drf:
+        return
+
+    _remove_file(project_path / "drf_exception_handler.py")
+
+def main():
+    handle_drf()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

django/{{ cookiecutter.project_slug }}/pyproject.toml

@@ -8,6 +8,11 @@ dependencies = [
     "django>=5.2.3",
     "django-admin-interface>=0.30.0",
     "django-debug-toolbar>=5.2.0",
+    {% if cookiecutter.use_drf == "y" %}
+    "djangorestframework>=3.16.0",
+    "django-cors-headers>=4.7.0",
+    "drf-spectacular>=0.28.0",
+    {% endif %}
     "django-environ>=0.12.0",
     "psycopg[binary]>=3.2.9",
     "whitenoise>=6.9.0",

django/{{ cookiecutter.project_slug }}/{{ cookiecutter.project_slug }}/drf_exception_handler.py

@@ -0,0 +1,36 @@
+# Third Party Packages
+from django.core.exceptions import PermissionDenied
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.http import Http404
+from rest_framework import exceptions
+from rest_framework.renderers import JSONRenderer
+from rest_framework.serializers import as_serializer_error
+from rest_framework.views import exception_handler
+
+
+def handle(exc, ctx):
+    """
+    This is a custom exception handler for our APIs.
+    cf. https://www.django-rest-framework.org/api-guide/exceptions/#custom-exception-handling
+    """
+    if isinstance(exc, DjangoValidationError):
+        exc = exceptions.ValidationError(as_serializer_error(exc))
+
+    if isinstance(exc, Http404):
+        exc = exceptions.NotFound()
+
+    if isinstance(exc, PermissionDenied):
+        exc = exceptions.PermissionDenied()
+
+    if ctx["request"].accepted_renderer.format != "json":
+        ctx["request"].accepted_renderer = JSONRenderer()
+    response = exception_handler(exc, ctx)
+
+    # If unexpected error occurs (server error, etc.)
+    if response is None:
+        return response
+
+    if isinstance(exc.detail, (list, dict)):
+        response.data = {"detail": response.data}
+
+    return response

django/{{ cookiecutter.project_slug }}/{{ cookiecutter.project_slug }}/settings/base.py

@@ -158,3 +158,31 @@
         "console": {"class": "logging.StreamHandler", "formatter": "verbose"},
     },
 }
+
+{% if cookiecutter.use_drf %}
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": (
+        "rest_framework.authentication.SessionAuthentication",
+        "rest_framework.authentication.BasicAuthentication",
+    ),
+    "DEFAULT_PERMISSION_CLASSES": (
+        "rest_framework.permissions.IsAuthenticated",
+    ),
+    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
+    "TEST_REQUEST_DEFAULT_FORMAT": "json",
+    "EXCEPTION_HANDLER": "{{ cookiecutter.project_slug }}.drf_exception_handler.handle",
+}
+
+SPECTACULAR_SETTINGS = {
+    "TITLE": "{{ cookiecutter.project_name }} API",
+    "DESCRIPTION": "API documentation for {{ cookiecutter.project_name }}",
+    "VERSION": "0.1",
+    "SERVE_INCLUDE_SCHEMA": False,
+    "COMPONENT_SPLIT_REQUEST": True,
+    "SERVE_PERMISSIONS": [
+        'rest_framework.permissions.IsAuthenticated',
+    ]
+}
+
+
+{% endif %}

django/{{ cookiecutter.project_slug }}/{{ cookiecutter.project_slug }}/settings/local.py

@@ -18,6 +18,11 @@
     FRONTEND_URL,
 ]
 
+{% if cookiecutter.use_drf == "y" %}
+# CORS
+CORS_ALLOW_ALL_ORIGINS = True
+CORS_ALLOW_CREDENTIALS = True
+{% endif %}
 # Django Debug Toolbar
 INSTALLED_APPS += ["debug_toolbar"]  # noqa: F405
 MIDDLEWARE += ["debug_toolbar.middleware.DebugToolbarMiddleware"]  # noqa: F405

django/{{ cookiecutter.project_slug }}/{{ cookiecutter.project_slug }}/settings/staging.py

@@ -8,3 +8,11 @@
 ALLOWED_HOSTS = [".v2.singular-it-test.de"]
 
 CSRF_TRUSTED_ORIGINS = ["https://*.v2.singular-it-test.de"]
+
+{% if cookiecutter.use_drf == "y" %}
+# CORS
+CORS_ALLOW_CREDENTIALS = True
+CORS_ALLOWED_ORIGIN_REGEXES = [
+    r"^https://.*\.v2\.singular-it-test\.de$",
+]
+{% endif %}

django/{{ cookiecutter.project_slug }}/{{ cookiecutter.project_slug }}/urls.py

@@ -19,9 +19,18 @@
 from django.contrib import admin
 from django.urls import path
 from django.urls.conf import include
-
+{% if cookiecutter.use_drf == "y" %}
+from drf_spectacular.views import (
+    SpectacularAPIView,
+    SpectacularSwaggerView,
+)
+{% endif %}
 urlpatterns = [
     path(".admin/", admin.site.urls),
+    {% if cookiecutter.use_drf == "y" %}
+    path("api/", SpectacularSwaggerView.as_view(), name="swagger-ui"),
+    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
+    {% endif %}
 ]
 
 if settings.DEBUG and "debug_toolbar" in settings.INSTALLED_APPS: