Verbesserung des AuthControllers und der Projektdokumentation

- AuthController.cs mit XML-Dokumentation aktualisiert und Parameter der Login-Methode umstrukturiert.
- Geänderte Klassendefinition zu partiell für Erweiterbarkeit.
- XML-Dokumentationsgenerierung zur Projektdatei hinzugefügt.
- Verbesserte Swagger-Dokumentation in Program.cs und korrigierte API-Beschreibung.
- Einführung einer neuen Datei Login.cs für ein strukturiertes Login-Datenmodell.

EnvelopeGenerator.GeneratorAPI/Controllers/AuthController.cs

@@ -10,14 +10,23 @@ using Microsoft.AspNetCore.Authorization;
 
 namespace EnvelopeGenerator.GeneratorAPI.Controllers
 {
+    /// <summary>
+    /// Controller verantwortlich für die Benutzer-Authentifizierung, einschließlich Anmelden, Abmelden und Überprüfung des Authentifizierungsstatus.
+    /// </summary>
     [Route("api/[controller]")]
     [ApiController]
-    public class AuthController : ControllerBase
+    public partial class AuthController : ControllerBase
     {
         private readonly ILogger<AuthController> _logger;
         private readonly IUserService _userService;
         private readonly IDirectorySearchService _dirSearchService;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthController"/> class.
+        /// </summary>
+        /// <param name="logger">The logger instance.</param>
+        /// <param name="userService">The user service instance.</param>
+        /// <param name="dirSearchService">The directory search service instance.</param>
         public AuthController(ILogger<AuthController> logger, IUserService userService, IDirectorySearchService dirSearchService)
         {
             _logger = logger;
@@ -25,10 +34,24 @@ namespace EnvelopeGenerator.GeneratorAPI.Controllers
             _dirSearchService = dirSearchService;
         }
 
-        //TODO: When a user group is created for signFlow, add a process to check if the user is in this group (like "PM_USER")
+        /// <summary>
+        /// Authentifiziert einen Benutzer und generiert ein JWT-Token. Wenn 'cookie' wahr ist, wird das Token als HTTP-Only-Cookie zurückgegeben.
+        /// </summary>
+        /// <param name="login">Benutzeranmeldedaten (Benutzername und Passwort).</param>
+        /// <param name="cookie">Wenn wahr, wird das JWT-Token auch als HTTP-Only-Cookie gesendet.</param>
+        /// <returns>
+        /// Gibt eine HTTP 200 OK-Antwort mit dem JWT-Token im Antwortkörper oder als HTTP-Only-Cookie zurück, wenn 'cookie' wahr ist.
+        /// </returns>
+        /// <response code="200">Erfolgreiche Anmeldung. Gibt das JWT-Token im Antwortkörper oder als Cookie zurück, wenn 'cookie' wahr ist.</response>
+        /// <response code="401">Unbefugt. Ungültiger Benutzername oder Passwort.</response>
+        /// <response code="500">Interner Serverfehler.</response>
+        [HttpPost]
+        [ProducesResponseType(typeof(string), StatusCodes.Status200OK, "text/javascript")]
+        [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+        [ProducesResponseType(StatusCodes.Status500InternalServerError)]
         [AllowAnonymous]
         [HttpPost]
-        public async Task<IActionResult> Login([FromBody] LogInDto login, bool cookie = false)
+        public async Task<IActionResult> Login([FromBody] LogInDto login, [FromQuery] bool cookie = false)
         {
             try
             {
@@ -52,13 +75,13 @@ namespace EnvelopeGenerator.GeneratorAPI.Controllers
 
                 // Create claims
                 var claims = new List<Claim>
-                {
-                    new (ClaimTypes.NameIdentifier, user.Id.ToString()),
-                    new (ClaimTypes.Name, user.Username),
-                    new (ClaimTypes.Surname, user.Name!),
-                    new (ClaimTypes.GivenName, user.Prename!),
-                    new (ClaimTypes.Email, user.Email!),
-                };
+                    {
+                        new (ClaimTypes.NameIdentifier, user.Id.ToString()),
+                        new (ClaimTypes.Name, user.Username),
+                        new (ClaimTypes.Surname, user.Name!),
+                        new (ClaimTypes.GivenName, user.Prename!),
+                        new (ClaimTypes.Email, user.Email!),
+                    };
 
                 // Create claimsIdentity
                 var claimsIdentity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme);
@@ -79,7 +102,7 @@ namespace EnvelopeGenerator.GeneratorAPI.Controllers
 
                 return Ok();
             }
-            catch(Exception ex)
+            catch (Exception ex)
             {
                 _logger.LogError(ex, "Unexpected error occurred.\n{ErrorMessage}", ex.Message);
                 return StatusCode(StatusCodes.Status500InternalServerError);
@@ -88,7 +111,7 @@ namespace EnvelopeGenerator.GeneratorAPI.Controllers
 
         [AllowAnonymous]
         [HttpPost]
-        [Route("/login")]
+        [Route("/form")]
         public async Task<IActionResult> Login([FromForm] LogInDto login)
         {
             return await Login(login, true);

EnvelopeGenerator.GeneratorAPI/EnvelopeGenerator.GeneratorAPI.csproj

@@ -4,6 +4,7 @@
     <TargetFrameworks>net9.0</TargetFrameworks>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>

EnvelopeGenerator.GeneratorAPI/Models/Login.cs

@@ -0,0 +1,15 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace EnvelopeGenerator.GeneratorAPI.Models;
+
+/// <summary>
+/// Anmeldedatenmodell
+/// </summary>
+/// <summary lang="en-US">
+/// Login data model 
+/// </summary>
+/// <param name="Username">Active Directory user name</param>
+/// <param name="Password">Active Directory password</param>
+public record Login([Required]string Username, [Required] string Password)
+{
+}

EnvelopeGenerator.GeneratorAPI/Program.cs

@@ -9,6 +9,7 @@ using Microsoft.EntityFrameworkCore;
 using System.Globalization;
 using Scalar.AspNetCore;
 using Microsoft.OpenApi.Models;
+using System.Reflection;
 
 var builder = WebApplication.CreateBuilder(args);
 
@@ -39,7 +40,7 @@ builder.Services.AddSwaggerGen(options =>
     {
         Version = "v1",
         Title = "signFLOW Absender-API",
-        Description = "\"Eine API zur Verwaltung der Erstellung, des Versands und der Nachverfolgung von Umschlägen in der signFLOW-Anwendung.",
+        Description = "Eine API zur Verwaltung der Erstellung, des Versands und der Nachverfolgung von Umschlägen in der signFLOW-Anwendung.",
         Contact = new OpenApiContact
         {
             Name = "Digital Data GmbH",
@@ -47,6 +48,9 @@ builder.Services.AddSwaggerGen(options =>
             Email = "info-flow@digitaldata.works"
         },
     });
+
+    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
 });
 builder.Services.AddOpenApi();
 // DbContext