feat: add interactive API docs (Swagger/ReDoc) via drf-spectacular

Exclude the unfinished Google login endpoint from the schema until social login is complete.

Author: Emidio Valereto Neto

.github/workflows/ci.yml

@@ -73,6 +73,6 @@ jobs:
           DJANGO_SETTINGS_MODULE: core.settings.docker
 
       - name: Run tests
-        run: python3 -m pytest tests/ -v -W error::DeprecationWarning
+        run: python3 -m pytest tests/ --ds=core.settings.docker -v -W error::DeprecationWarning
         env:
           DJANGO_SETTINGS_MODULE: core.settings.docker

.gitignore

@@ -195,9 +195,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
 #   you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 # Temporary file for partial code execution
@@ -218,4 +218,4 @@ __marimo__/
 .streamlit/secrets.toml
 
 # Static
-/media
+/media

accounts/views.py

@@ -7,6 +7,7 @@
 from allauth.socialaccount.providers.google.views import GoogleOAuth2Adapter
 from allauth.socialaccount.providers.oauth2.client import OAuth2Client
 
+from drf_spectacular.utils import extend_schema
 from .serializers import RegisterSerializer, UserSerializer
 
 
@@ -30,6 +31,7 @@ def put(self, request):
         return Response(serializer.data)
 
 
+@extend_schema(exclude=True)
 class GoogleLoginView(SocialLoginView):
     adapter_class = GoogleOAuth2Adapter
     callback_url = "http://localhost:3000/auth/google/callback"

core/settings/base.py

@@ -25,8 +25,12 @@
     "dj_rest_auth",
     "dj_rest_auth.registration",
 
+    # drf-spectacular
+    "drf_spectacular",
+
     # Allauth
     "allauth",
+    "allauth.account",
     "allauth.socialaccount",
     "allauth.socialaccount.providers.google",
     "allauth.socialaccount.providers.github",
@@ -51,6 +55,28 @@
     "django.middleware.clickjacking.XFrameOptionsMiddleware",
 ]
 
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": ("rest_framework_simplejwt.authentication.JWTAuthentication",),
+    "DEFAULT_PERMISSION_CLASSES": ("rest_framework.permissions.IsAuthenticated",),
+    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
+    "PAGE_SIZE": 20,
+    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
+}
+
+SPECTACULAR_SETTINGS = {
+    "TITLE": "Simlog API",
+    "DESCRIPTION": "Django REST API for a flight simulator companion app.",
+    "VERSION": "1.0",
+    "SERVE_INCLUDE_SCHEMA": False,
+
+    "AUTHENTICATION_CLASSES": (
+        "rest_framework_simplejwt.authentication.JWTAuthentication",
+    ),
+    "SWAGGER_UI_SETTINGS": {
+        "persistAuthorization": True,
+    },
+}
+
 ROOT_URLCONF = "core.urls"
 
 SITE_ID = 1
@@ -113,12 +139,5 @@
 
 DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
 
-REST_FRAMEWORK = {
-    "DEFAULT_AUTHENTICATION_CLASSES": ("rest_framework_simplejwt.authentication.JWTAuthentication",),
-    "DEFAULT_PERMISSION_CLASSES": ("rest_framework.permissions.IsAuthenticated",),
-    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
-    "PAGE_SIZE": 20,
-}
-
 MEDIA_URL = "/media/"
 MEDIA_ROOT = os.path.join(BASE_DIR, "media")

core/urls.py

@@ -1,12 +1,22 @@
 from django.contrib import admin
 from django.urls import path, include
 from django.conf import settings
+
 from django.conf.urls.static import static
+from django.views.generic import RedirectView
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
 
 urlpatterns = [
     path("admin/", admin.site.urls),
     path("api/auth/", include("accounts.urls")),
     path("api/flights/", include("logbook.urls")),
     path("api/simbrief/", include("simbrief.urls")),
     path("api/", include("checklist.urls")),
+    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
+    path("api/docs/", SpectacularSwaggerView.as_view(
+        url_name="schema",
+        ),
+        name="swagger-ui"),
+    path("", RedirectView.as_view(pattern_name="swagger-ui")),
+
 ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

requirements/base.txt

@@ -7,3 +7,8 @@ requests>=2.31
 whitenoise>=6.7
 django-cors-headers>=4.3
 pillow>=12.0,<13.0
+django-allauth>=65.18,<66.0
+dj-rest-auth>=7.2,<8.0
+oauthlib>=3.3,<4.0
+cryptography>=49.0,<50.0
+drf-spectacular>=0.29,<0.30