Authentication api docs

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

@@ -13,6 +13,12 @@ use Source\UseCases\Users\Authenticate\APIPresenter;
 use Source\UseCases\Users\Authenticate\AuthenticateUseCase;
 use Source\UseCases\Users\Authenticate\UserCreationException;
 
+
+/**
+ * @group Authentication
+ *
+ * This set of routes deals with authentication with the application through SAML and application login.
+ */
 class AuthController extends ApiController
 {
     protected CookieJar $cookieJar;
@@ -30,15 +36,31 @@ class AuthController extends ApiController
     }
 
     /**
+     * Login request to application
+     *
+     * This endpoint returns a token that can be used in other endpoints as well as setting a cookie.
+     * One does not need to make a request to this if they have a valid token.
+     *
+     * @bodyParam email string required The email of the login user. Example: sithL0rd@senate.com
+     * @bodyParam password string required The password of the user to login as. Example: I am the senate
+     *
+     * @response 422 {"message":"The given data was invalid.","errors":{"email":["The email field is required."],"password":["The password field is required."]}}
+     *
      * @param AuthenticateUseCase $authenticateUseCase
      * @return JsonResponse
      * @throws AuthenticationException
      * @throws EntityNotFoundException
+     * @throws \Illuminate\Validation\ValidationException
      */
     public function login(AuthenticateUseCase $authenticateUseCase): JsonResponse
     {
         $presenter = new APIPresenter();
 
+        $this->validate($this->request, [
+            'email' => 'required|string|email',
+            'password' => 'required|string',
+        ]);
+
         $authenticateUseCase->attempt($presenter, $this->request->all());
 
         return $this->respondWithData($presenter->getViewModel())->withCookie(
@@ -51,6 +73,10 @@ class AuthController extends ApiController
     }
 
     /**
+     * Start a saml login request
+     *
+     * This route redirects the user to the running SAML authentication instance to start authentication with SAML
+     *
      * @param \Source\UseCases\Users\Authenticate\AuthenticateUseCase $authenticateUseCase
      * @return \Illuminate\Http\RedirectResponse
      */
@@ -60,9 +86,14 @@ class AuthController extends ApiController
     }
 
     /**
+     * Handle SAML login
+     *
+     * This API is only meant to be used by SAML after a login.
+     *
      * @param AuthenticateUseCase $authenticateUseCase
      * @return mixed
      * @throws EntityNotFoundException
+     * @throws \Source\Exceptions\EntityExistsException
      */
     public function handle(AuthenticateUseCase $authenticateUseCase)
     {
@@ -86,6 +117,10 @@ class AuthController extends ApiController
     }
 
     /**
+     * Log out
+     *
+     * This endpoint logs out of saml and expires the associated api/login token and cookie.
+     *
      * @param AuthenticateUseCase $authenticateUseCase
      * @return RedirectResponse
      */