Merge pull request #659 from Blazam-App/v1-Dev

Improve API documentation

BLAZAM/BLAZAM.csproj

@@ -6,7 +6,7 @@
 		<ImplicitUsings>enable</ImplicitUsings>
 		<ServerGarbageCollection>false</ServerGarbageCollection>
 		<AssemblyVersion>1.2.0</AssemblyVersion>
-		<Version>2024.11.24.1848</Version>
+		<Version>2024.11.25.0412</Version>
 		<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
 		<RootNamespace>BLAZAM</RootNamespace>
 		<GenerateDocumentationFile>True</GenerateDocumentationFile>

BLAZAM/Pages/API/Data/NewUserDetails.cs

@@ -3,11 +3,22 @@
 
 namespace BLAZAM.Pages.API.Data
 {
-
+    /// <summary>
+    /// Request package for creation of a templated user
+    /// </summary>
     public class NewUserDetails
     {
+        /// <summary>
+        /// The given name for this user
+        /// </summary>
         public string FirstName { get; set; }
+        /// <summary>
+        /// The middle name for this user
+        /// </summary>
         public string? MiddleName { get; set; }
+        /// <summary>
+        /// The surname for this user
+        /// </summary>
         public string? LastName { get; set; }
         /// <summary>
         /// If set, overrides the template generated username
@@ -22,9 +33,21 @@ public class NewUserDetails
         /// </remarks>
         public string? OU { get; set; }
 
-
+        /// <summary>
+        /// The fields to set for this user. Template field with values will also
+        /// be applied.
+        /// </summary>
         public List<NewUserField>? Fields { get; set; }
+        /// <summary>
+        /// A list of group SID's to assign for this user. Template groups will also
+        /// be applied.
+        /// </summary>
         public List<string>? Groups { get; set; }
+
+        /// <summary>
+        /// If the template is set to send a welcome email, and requests a destination, will be sent
+        /// to this email address.
+        /// </summary>
         public string? SendWelcomeEmailTo { get; set; }
     }
     public class NewUserDetailsExample

BLAZAM/Pages/API/Data/NewUserField.cs

@@ -2,9 +2,18 @@
 
 namespace BLAZAM.Pages.API.Data
 {
+    /// <summary>
+    /// Represents an Active Directory attribute field to set for thee new user
+    /// </summary>
     public class NewUserField
     {
+        /// <summary>
+        /// The attribute name as set in Active Directory
+        /// </summary>
         public string FieldName { get; set; }
+        /// <summary>
+        /// The value to set for this attribute field
+        /// </summary>
         public object? FieldValue { get; set; }
     }
 }

BLAZAM/Pages/API/v1/Templates.cs

@@ -63,10 +63,11 @@ public Templates(NotificationGenerationService ouNotificationService, EmailServi
         ///
         /// </remarks>
         /// <param name="templateId">The ID of the template to execute.</param>
-        /// <param name="newUserData">A JSON formatted key-value list of attribute names and values.</param>
-        /// <response code="200">Returns details about the user performing the test.</response>
+        /// <param name="newUserDetails">A complete NewUserDetails request schema</param>
+        /// <response code="200">Returns the DN of the created user.</response>
         /// <response code="401">Unauthorized - The user is not authenticated.</response>
         /// <response code="403">Forbidden - The user does not have the required role.</response>
+        /// <response code="422">Unprocessable - The creation request cannot be processed due to an internal error.</response>
         [HttpPost]
         [Route("/api/v1/templates/execute/{templateId}")]
 
@@ -99,7 +100,12 @@ public async Task<IActionResult> Execute(int templateId, [FromBody] NewUserDetai
                     MiddleName = newUserDetails.MiddleName,
                     Surname = newUserDetails.LastName
                 };
+
                 var newUser = template.GenerateTemplateUser(newUserName, Directory);
+                if (!newUserDetails.Username.IsNullOrEmpty())
+                {
+                    newUser.SamAccountName = newUserDetails.Username;
+                }
                 var password = newUser.NewPassword.ToPlainText().ToSecureString();
                 foreach (var fieldValue in template.EffectiveFieldValues)
                 {
@@ -191,15 +197,12 @@ public async Task<IActionResult> Execute(int templateId, [FromBody] NewUserDetai
                     {
 
                     }
-                    return new CreatedResult(newUser.OU,newUser.CanonicalName);
+                    return new CreatedResult(newUser.OU, newUser.DN);
                 }
                 else
                 {
-                    return new UnprocessableEntityObjectResult(result.FailedSteps.Select(s=>s.Exception.InnerException!=null?s.Exception.InnerException.Message:s.Exception.Message));
+                    return new UnprocessableEntityObjectResult(result.FailedSteps.Select(s => s.Exception.InnerException != null ? s.Exception.InnerException.Message : s.Exception.Message));
                 }
-
-
-                var tdest = 3;
             }
             else
             {
@@ -212,7 +215,7 @@ public async Task<IActionResult> Execute(int templateId, [FromBody] NewUserDetai
         /// <summary>
         /// Returns all user creation templates the user has access to.
         /// </summary>
-        /// <response code="200">Returns details about the user performing the test.</response>
+        /// <response code="200">Returns a list of user creation templates.</response>
         /// <response code="401">Unauthorized - The user is not authenticated.</response>
         /// <response code="403">Forbidden - The user does not have the required role.</response>
         [HttpGet]