From ca78f43f732ff9560cdbbd46d2e2cf3267c55b5a Mon Sep 17 00:00:00 2001
From: eee4 <41441600+eee4@users.noreply.github.com>
Date: Tue, 22 Jul 2025 12:06:22 +0200
Subject: [PATCH] chore: documentation for category modification

---
 Controllers/CategoryController.cs | 50 +++++++++++++++++++++----------
 1 file changed, 34 insertions(+), 16 deletions(-)

diff --git a/Controllers/CategoryController.cs b/Controllers/CategoryController.cs
index 3cacd7a..ff65760 100644
--- a/Controllers/CategoryController.cs
+++ b/Controllers/CategoryController.cs
@@ -155,31 +155,49 @@ public class CategoryController : ControllerBase
         return Ok(new { Status = "ok" });
     }
 
+    // PATCH /api/v1/categories/1
+    /// <summary>
+    /// [AUTHED] Modify an existing category
+    /// </summary>
+    /// <remarks>
+    /// Allows authorized users to modify categories.
+    /// <br/><br/>
+    /// Has CORS set.
+    /// </remarks>
+    /// <param name="id">Id of the category which shall be modified</param>
+    /// <param name="updatedCategory">DTO with new name and description. Id and creation date are ignored.</param>
+    /// <response code="200">Returned on valid request</response>
+    /// <response code="400">Returned when category name is empty or null</response>
+    /// <response code="404">Returned when no such category exists</response>
     [HttpPatch("{id}")]
     [Authorize]
     [EnableCors]
-    [ProducesResponseType(typeof(QuoteShortDTO), 200)]
+    [ProducesResponseType(typeof(CategoryShortDTO), 200)]
     [ProducesResponseType(typeof(ErrorDTO), 400)]
     [ProducesResponseType(typeof(ErrorDTO), 404)]
-    public async Task<IActionResult> EditCategory(int id, [FromBody] CategoryShortDTO updatedCategory)
-    {
-        Category? cat= await _db.Categories.FirstOrDefaultAsync(c => c.Id == id);
-
+    public async Task<IActionResult> EditCategory(int id, [FromBody] CategoryShortDTO updatedCategory)
+    {
+        // Find the category to modify
+        Category? cat = await _db.Categories.FirstOrDefaultAsync(c => c.Id == id);
+
+        // Failed?
         if (cat == null)
             return NotFound(new { status = "error", error_msg = "Category not found" });
 
-        if (string.IsNullOrWhiteSpace(updatedCategory.Name) || string.IsNullOrWhiteSpace(updatedCategory.Description))
-            return BadRequest(new ErrorDTO { Status = "error", Error_msg = "Text and author are required." });
-
-        cat.Name=updatedCategory.Name;
-        cat.Description=updatedCategory.Description;
-
-        await _db.SaveChangesAsync();
-        return Ok(cat.ToCategoryShortDTO());
-    }
+        // Otherwise, ensure the category name is not empty or null
+        if (string.IsNullOrWhiteSpace(updatedCategory.Name))
+            return BadRequest(new ErrorDTO { Status = "error", Error_msg = "Category name cannot be empty." });
 
-    // TODO: Update category
-    // PATCH /api/v1/categories/1
+        // Update the fields
+        cat.Name = updatedCategory.Name;
+        cat.Description = updatedCategory.Description;
+        // Note the user cannot modify the createdAt field,
+        // and we do not store last modification date.
+        await _db.SaveChangesAsync();
+
+        // Return the modified category to user
+        return Ok(cat.ToCategoryShortDTO());
+    }
 
 }