swagger support (#98)

* feat: Integrate drf-spectacular for OpenAPI documentation and add schema endpoints

* fix: Add TEMPLATES and STATIC_URL configuration for drf-spectacular

* fix: Add trailing slashes to API docs paths and enable DEBUG mode

* fix: Replace Pydantic models with inline schemas in Swagger decorators

* fix: Update OpenAPI responses to use OpenApiResponse for consistency

---------

Co-authored-by: Amit Prakash <[email protected]>

Author: iamitprakash

requirements.txt

@@ -26,3 +26,4 @@ PyJWT==2.10.1
 requests==2.32.3
 email-validator==2.2.0
 testcontainers[mongodb]==4.10.0
+drf-spectacular==0.28.0

todo/views/auth.py

@@ -4,6 +4,8 @@
 from rest_framework import status
 from django.http import HttpResponseRedirect, HttpResponse
 from django.conf import settings
+from drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiExample, OpenApiResponse
+from drf_spectacular.types import OpenApiTypes
 from todo.services.google_oauth_service import GoogleOAuthService
 from todo.services.user_service import UserService
 from todo.utils.google_jwt_utils import (
@@ -24,6 +26,32 @@
 
 
 class GoogleLoginView(APIView):
+    @extend_schema(
+        operation_id="google_login",
+        summary="Initiate Google OAuth login",
+        description="Redirects to Google OAuth authorization URL or returns JSON response with auth URL",
+        tags=["auth"],
+        parameters=[
+            OpenApiParameter(
+                name="redirectURL",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="URL to redirect after successful authentication",
+                required=False,
+            ),
+            OpenApiParameter(
+                name="format",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="Response format: 'json' for JSON response, otherwise redirects",
+                required=False,
+            ),
+        ],
+        responses={
+            200: OpenApiResponse(description="Google OAuth URL generated successfully"),
+            302: OpenApiResponse(description="Redirect to Google OAuth URL"),
+        },
+    )
     def get(self, request: Request):
         redirect_url = request.query_params.get("redirectURL")
         auth_url, state = GoogleOAuthService.get_authorization_url(redirect_url)
@@ -51,6 +79,40 @@ class GoogleCallbackView(APIView):
     The frontend implementation will redirect to the frontend and process the callback via POST request.
     """
 
+    @extend_schema(
+        operation_id="google_callback",
+        summary="Handle Google OAuth callback",
+        description="Processes the OAuth callback from Google and creates/updates user account",
+        tags=["auth"],
+        parameters=[
+            OpenApiParameter(
+                name="code",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="Authorization code from Google",
+                required=True,
+            ),
+            OpenApiParameter(
+                name="state",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="State parameter for CSRF protection",
+                required=True,
+            ),
+            OpenApiParameter(
+                name="error",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="Error from Google OAuth",
+                required=False,
+            ),
+        ],
+        responses={
+            200: OpenApiResponse(description="OAuth callback processed successfully"),
+            400: OpenApiResponse(description="Bad request - invalid parameters"),
+            500: OpenApiResponse(description="Internal server error"),
+        },
+    )
     def get(self, request: Request):
         if "error" in request.query_params:
             error = request.query_params.get("error")
@@ -274,6 +336,17 @@ def _set_auth_cookies(self, response, tokens):
 
 
 class GoogleAuthStatusView(APIView):
+    @extend_schema(
+        operation_id="google_auth_status",
+        summary="Check authentication status",
+        description="Check if the user is authenticated and return user information",
+        tags=["auth"],
+        responses={
+            200: OpenApiResponse(description="Authentication status retrieved successfully"),
+            401: OpenApiResponse(description="Unauthorized - invalid or missing token"),
+            500: OpenApiResponse(description="Internal server error"),
+        },
+    )
     def get(self, request: Request):
         access_token = request.COOKIES.get("ext-access")
 
@@ -304,6 +377,17 @@ def get(self, request: Request):
 
 
 class GoogleRefreshView(APIView):
+    @extend_schema(
+        operation_id="google_refresh_token",
+        summary="Refresh access token",
+        description="Refresh the access token using the refresh token from cookies",
+        tags=["auth"],
+        responses={
+            200: OpenApiResponse(description="Token refreshed successfully"),
+            401: OpenApiResponse(description="Unauthorized - invalid or missing refresh token"),
+            500: OpenApiResponse(description="Internal server error"),
+        },
+    )
     def get(self, request: Request):
         refresh_token = request.COOKIES.get("ext-refresh")
 
@@ -344,9 +428,44 @@ def _get_cookie_config(self):
 
 
 class GoogleLogoutView(APIView):
+    @extend_schema(
+        operation_id="google_logout",
+        summary="Logout user",
+        description="Logout the user by clearing authentication cookies",
+        tags=["auth"],
+        parameters=[
+            OpenApiParameter(
+                name="redirectURL",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="URL to redirect after logout",
+                required=False,
+            ),
+            OpenApiParameter(
+                name="format",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="Response format: 'json' for JSON response, otherwise redirects",
+                required=False,
+            ),
+        ],
+        responses={
+            200: OpenApiResponse(description="Logout successful"),
+            302: OpenApiResponse(description="Redirect to specified URL or home page"),
+        },
+    )
     def get(self, request: Request):
         return self._handle_logout(request)
 
+    @extend_schema(
+        operation_id="google_logout_post",
+        summary="Logout user (POST)",
+        description="Logout the user by clearing authentication cookies (POST method)",
+        tags=["auth"],
+        responses={
+            200: OpenApiResponse(description="Logout successful"),
+        },
+    )
     def post(self, request: Request):
         return self._handle_logout(request)
 
@@ -371,10 +490,9 @@ def _handle_logout(self, request: Request):
             redirect_url = redirect_url or "/"
             response = HttpResponseRedirect(redirect_url)
 
-        response.delete_cookie("ext-access", path="/")
-        response.delete_cookie("ext-refresh", path="/")
-        response.delete_cookie(settings.SESSION_COOKIE_NAME, path="/")
-        request.session.flush()
+        config = self._get_cookie_config()
+        response.delete_cookie("ext-access", **config)
+        response.delete_cookie("ext-refresh", **config)
 
         return response
 

todo/views/health.py

@@ -1,12 +1,23 @@
 from rest_framework.views import APIView
 from rest_framework.response import Response
+from drf_spectacular.utils import extend_schema, OpenApiResponse
 from todo.constants.health import AppHealthStatus, ComponentHealthStatus
 from todo_project.db.config import DatabaseManager
 
 database_manager = DatabaseManager()
 
 
 class HealthView(APIView):
+    @extend_schema(
+        operation_id="health_check",
+        summary="Health check",
+        description="Check the health status of the application and its components",
+        tags=["health"],
+        responses={
+            200: OpenApiResponse(description="Application is healthy"),
+            503: OpenApiResponse(description="Application is unhealthy"),
+        },
+    )
     def get(self, request):
         global database_manager
         is_db_healthy = database_manager.check_database_health()

todo/views/task.py

@@ -5,6 +5,8 @@
 from rest_framework.request import Request
 from rest_framework.exceptions import ValidationError
 from django.conf import settings
+from drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiExample, OpenApiResponse
+from drf_spectacular.types import OpenApiTypes
 from todo.middlewares.jwt_auth import get_current_user_info
 from todo.serializers.get_tasks_serializer import GetTaskQueryParamsSerializer
 from todo.serializers.create_task_serializer import CreateTaskSerializer
@@ -20,6 +22,31 @@
 
 
 class TaskListView(APIView):
+    @extend_schema(
+        operation_id="get_tasks",
+        summary="Get paginated list of tasks",
+        description="Retrieve a paginated list of tasks with optional filtering and sorting",
+        tags=["tasks"],
+        parameters=[
+            OpenApiParameter(
+                name="page",
+                type=OpenApiTypes.INT,
+                location=OpenApiParameter.QUERY,
+                description="Page number for pagination",
+            ),
+            OpenApiParameter(
+                name="limit",
+                type=OpenApiTypes.INT,
+                location=OpenApiParameter.QUERY,
+                description="Number of tasks per page",
+            ),
+        ],
+        responses={
+            200: OpenApiResponse(description="Successful response"),
+            400: OpenApiResponse(description="Bad request"),
+            500: OpenApiResponse(description="Internal server error"),
+        },
+    )
     def get(self, request: Request):
         """
         Retrieve a paginated list of tasks.
@@ -30,6 +57,18 @@ def get(self, request: Request):
         response = TaskService.get_tasks(page=query.validated_data["page"], limit=query.validated_data["limit"])
         return Response(data=response.model_dump(mode="json", exclude_none=True), status=status.HTTP_200_OK)
 
+    @extend_schema(
+        operation_id="create_task",
+        summary="Create a new task",
+        description="Create a new task with the provided details",
+        tags=["tasks"],
+        request=CreateTaskSerializer,
+        responses={
+            201: OpenApiResponse(description="Task created successfully"),
+            400: OpenApiResponse(description="Bad request"),
+            500: OpenApiResponse(description="Internal server error"),
+        },
+    )
     def post(self, request: Request):
         """
         Create a new task.
@@ -92,6 +131,25 @@ def _handle_validation_errors(self, errors):
 
 
 class TaskDetailView(APIView):
+    @extend_schema(
+        operation_id="get_task_by_id",
+        summary="Get task by ID",
+        description="Retrieve a single task by its unique identifier",
+        tags=["tasks"],
+        parameters=[
+            OpenApiParameter(
+                name="task_id",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.PATH,
+                description="Unique identifier of the task",
+            ),
+        ],
+        responses={
+            200: OpenApiResponse(description="Task retrieved successfully"),
+            404: OpenApiResponse(description="Task not found"),
+            500: OpenApiResponse(description="Internal server error"),
+        },
+    )
     def get(self, request: Request, task_id: str):
         """
         Retrieve a single task by ID.
@@ -100,12 +158,58 @@ def get(self, request: Request, task_id: str):
         response_data = GetTaskByIdResponse(data=task_dto)
         return Response(data=response_data.model_dump(mode="json"), status=status.HTTP_200_OK)
 
+    @extend_schema(
+        operation_id="delete_task",
+        summary="Delete task",
+        description="Delete a task by its unique identifier",
+        tags=["tasks"],
+        parameters=[
+            OpenApiParameter(
+                name="task_id",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.PATH,
+                description="Unique identifier of the task to delete",
+            ),
+        ],
+        responses={
+            204: OpenApiResponse(description="Task deleted successfully"),
+            404: OpenApiResponse(description="Task not found"),
+            500: OpenApiResponse(description="Internal server error"),
+        },
+    )
     def delete(self, request: Request, task_id: str):
         user = get_current_user_info(request)
         task_id = ObjectId(task_id)
         TaskService.delete_task(task_id, user["user_id"])
         return Response(status=status.HTTP_204_NO_CONTENT)
 
+    @extend_schema(
+        operation_id="update_task",
+        summary="Update or defer task",
+        description="Partially update a task or defer it based on the action parameter",
+        tags=["tasks"],
+        parameters=[
+            OpenApiParameter(
+                name="task_id",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.PATH,
+                description="Unique identifier of the task",
+            ),
+            OpenApiParameter(
+                name="action",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="Action to perform: 'update' or 'defer'",
+            ),
+        ],
+        request=UpdateTaskSerializer,
+        responses={
+            200: OpenApiResponse(description="Task updated successfully"),
+            400: OpenApiResponse(description="Bad request"),
+            404: OpenApiResponse(description="Task not found"),
+            500: OpenApiResponse(description="Internal server error"),
+        },
+    )
     def patch(self, request: Request, task_id: str):
         """
         Partially updates a task by its ID.