feat(authentication): enhance LogoutView & LogoutAllView with detailed OpenAPI response schemas

authentication/views.py

-from drf_spectacular.utils import extend_schema
+from drf_spectacular.utils import OpenApiResponse, extend_schema
 from knox.views import LoginView as KnoxLoginView
 from rest_framework import parsers, renderers, serializers, status, views
 from rest_framework.response import Response
 
 from authentication.errors import OAuth2Error
-from authentication.serializers import TokenRequestSerializer, TokenResponseSerializer
+from authentication.serializers import (
+    TokenErrorSerializer,
+    TokenRequestSerializer,
+    TokenResponseSerializer,
+)
 
 
 @extend_schema(
     request=TokenRequestSerializer,
     responses={
         200: TokenResponseSerializer,
-        400: {
-            "description": "Invalid request, such as both or none of crsid and last name are "
-            "provided, or no matching user."
-        },
-        401: {"description": "Authentication credentials were not provided or are invalid."},
-        403: {"description": "The user is not authorized to access this resource."},
+        400: OpenApiResponse(
+            response=TokenErrorSerializer,
+            description=(
+                "Invalid request, such as both or none of crsid and last name are provided, "
+                "or no matching user."
+            ),
+        ),
     },
     tags=["Token Management"],
 )
@@ -84,6 +89,18 @@ class LoginView(KnoxLoginView):
         return exception_handler
 
 
+@extend_schema(
+    tags=["Token Management"],
+    summary="Log out a user",
+    description="Endpoint to log out the current logged-in user by revoking their auth token.",
+    responses={
+        204: OpenApiResponse(description="Successfully logged out, no content to return."),
+        401: OpenApiResponse(
+            description="Unauthorized request, possibly due to an invalid token."
+        ),
+    },
+    methods=["POST"],
+)
 class LogoutView(views.APIView):
     throttle_classes = ()
     versioning_class = None
@@ -97,6 +114,21 @@ class LogoutView(views.APIView):
         return self.get_post_response(request)
 
 
+@extend_schema(
+    tags=["Token Management"],
+    summary="Log out all sessions for a user",
+    description="Endpoint to log out the current logged-in user from all sessions "
+    "by revoking all their auth tokens.",
+    responses={
+        204: OpenApiResponse(
+            description="Successfully logged out from all sessions, no content to return."
+        ),
+        401: OpenApiResponse(
+            description="Unauthorized request, possibly due to an invalid token."
+        ),
+    },
+    methods=["POST"],
+)
 class LogoutAllView(views.APIView):
     throttle_classes = ()
     versioning_class = None