📝 Add Swagger Docs

arbisoft_sessions_portal/settings/base.py

@@ -45,6 +45,7 @@
     'DEFAULT_FILTER_BACKENDS': (
         'django_filters.rest_framework.DjangoFilterBackend',
     ),
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
 }
 
 # Application definition
@@ -59,6 +60,7 @@
     'django.contrib.staticfiles',
     'rest_framework',
     'django_filters',
+    'drf_spectacular',
     'users',
     'events'
 ]

arbisoft_sessions_portal/urls.py

@@ -18,9 +18,14 @@
 from django.urls import path, include
 from django.conf.urls.static import static
 from django.conf import settings
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView
 
 
 urlpatterns = [
+    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
+    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
+    path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
+
     path('admin/', admin.site.urls),
     path('api/v1/users/', include('users.v1.urls')),
     path('api/v1/events/', include('events.v1.urls')),

events/v1/views.py

@@ -1,3 +1,4 @@
+from drf_spectacular.utils import extend_schema
 from rest_framework import status
 from rest_framework.generics import ListAPIView
 from rest_framework.pagination import PageNumberPagination
@@ -11,6 +12,24 @@
 
 class EventTypeListView(APIView):
     """ View for listing the event types """
+
+    @extend_schema(
+        responses={
+            200: {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "label": {"type": "string", "example": "SESSION"},
+                        "key": {"type": "string", "example": "session"}
+                    }
+                },
+                "example": [
+                    {"label": "SESSION", "key": "session"}
+                ]
+            }
+        }
+    )
     def get(self, request, *args, **kwargs):
         """ Get the event types """
         event_types = [

requirements/base.txt

@@ -6,6 +6,7 @@ django-cors-headers==4.6.0
 django-filter==24.3
 djangorestframework==3.15.2
 djangorestframework-simplejwt==5.3.1
+drf-spectacular==0.28.0
 idna==3.10
 Markdown==3.7
 pillow==11.1.0

users/v1/views.py

@@ -1,3 +1,4 @@
+from drf_spectacular.utils import extend_schema
 from rest_framework.exceptions import ValidationError
 from rest_framework.response import Response
 from rest_framework.views import APIView
@@ -17,6 +18,61 @@ class LoginUserView(APIView):
 
     permission_classes = []
 
+    @extend_schema(
+        request=LoginUserSerializer,
+        responses={
+            200: {
+                "type": "object",
+                "properties": {
+                    "refresh": {
+                        "type": "string",
+                        "description": "JWT refresh token",
+                        "example": "eyJ0eXAiOiJKV1QiLCJhbGc..."
+                    },
+                    "access": {
+                        "type": "string",
+                        "description": "JWT access token",
+                        "example": "eyJ0eXAiOiJKV1QiLCJhbGc..."
+                    },
+                    "user_info": {
+                        "type": "object",
+                        "properties": {
+                            "full_name": {
+                                "type": "string",
+                                "example": "John Doe"
+                            },
+                            "first_name": {
+                                "type": "string",
+                                "example": "John"
+                            },
+                            "last_name": {
+                                "type": "string",
+                                "example": "Doe"
+                            },
+                            "avatar": {
+                                "type": "string",
+                                "format": "uri",
+                                "example": "https://lh3.googleusercontent.com/a/photo"
+                            }
+                        }
+                    }
+                }
+            },
+            400: {
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "type": "string",
+                        "enum": [
+                            "Google Authentication failed",
+                            "Not arbisoft user."
+                        ]
+                    }
+                }
+            }
+        },
+        description="Authenticate user using Google OAuth2 token and return JWT tokens",
+    )
     def post(self, request):
         """ Log in the user """
 
@@ -58,6 +114,12 @@ def post(self, request):
 class HelloWorldView(APIView):
     """ View for testing the API """
 
+    @extend_schema(
+        responses={200: {"type": "string", "example": "Hello World"}}
+    )
     def get(self, request):
-        """ Get the response """
+        """
+        This endpoint returns a simple "Hello World" response.
+        It can be used to verify that the API is up and running.
+        """
         return Response("Hello World")