Ralph iteration 1: work in progress

backend/app/Http/Controllers/Api/AuthController.php

@@ -10,8 +10,37 @@ use Illuminate\Support\Facades\Hash;
 use Illuminate\Support\Facades\Redis;
 use Illuminate\Support\Facades\Validator;
 
+/**
+ * @group Authentication
+ *
+ * Endpoints for JWT authentication and session lifecycle.
+ */
 class AuthController extends Controller
 {
+    /**
+     * Login and get tokens
+     *
+     * Authenticate with email and password to receive an access token and refresh token.
+     *
+     * @bodyParam email string required User email address. Example: user@example.com
+     * @bodyParam password string required User password. Example: secret123
+     *
+     * @response 200 {
+     *   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+     *   "refresh_token": "abc123def456",
+     *   "token_type": "bearer",
+     *   "expires_in": 3600,
+     *   "user": {
+     *     "id": "550e8400-e29b-41d4-a716-446655440000",
+     *     "name": "Alice Johnson",
+     *     "email": "user@example.com",
+     *     "role": "manager"
+     *   }
+     * }
+     * @response 401 {"message":"Invalid credentials"}
+     * @response 403 {"message":"Account is inactive"}
+     * @response 422 {"errors":{"email":["The email field is required."],"password":["The password field is required."]}}
+     */
     public function login(Request $request): JsonResponse
     {
         $validator = Validator::make($request->all(), [
@@ -56,6 +85,22 @@ class AuthController extends Controller
         ]);
     }
 
+    /**
+     * Refresh access token
+     *
+     * Exchange a valid refresh token for a new access token and refresh token pair.
+     *
+     * @authenticated
+     * @bodyParam refresh_token string required Refresh token returned by login. Example: abc123def456
+     *
+     * @response 200 {
+     *   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+     *   "refresh_token": "newtoken123",
+     *   "token_type": "bearer",
+     *   "expires_in": 3600
+     * }
+     * @response 401 {"message":"Invalid or expired refresh token"}
+     */
     public function refresh(Request $request): JsonResponse
     {
         $refreshToken = $request->input('refresh_token');
@@ -89,6 +134,16 @@ class AuthController extends Controller
         ]);
     }
 
+    /**
+     * Logout current session
+     *
+     * Invalidate a refresh token and end the active authenticated session.
+     *
+     * @authenticated
+     * @bodyParam refresh_token string Optional refresh token to invalidate immediately. Example: abc123def456
+     *
+     * @response 200 {"message":"Logged out successfully"}
+     */
     public function logout(Request $request): JsonResponse
     {
         $user = $request->user();