chore: update documentation for new quotes endpoints

Controllers/QuoteController.cs

@@ -75,7 +75,7 @@ public class QuotesController : ControllerBase
 
     // GET /api/v1/quotes/{id}
     /// <summary>
-    /// [AUTH] Get specified quote summary
+    /// [AUTHED] Get specified quote summary
     /// </summary>
     /// <param name="id">The quote id in question</param>
     /// <returns>A quote: id, quote content and author, imageUrl and categories if successful, otherwise: error message</returns>
@@ -222,50 +222,110 @@ public class QuotesController : ControllerBase
 
     }
 
-
+    // DELETE /api/v1/quotes/{id}
+    /// <summary>
+    /// [AUTHED] Delete a quote
+    /// </summary>
+    /// <remarks>
+    /// Deletes a quote, granted it exists. <br/>
+    /// <br/>
+    /// <i>
+    /// Is this the best practice? Marking the quote as hidden is also an option.
+    /// </i> ~eee4
+    /// </remarks>
+    /// <returns>Json with status</returns>
+    /// <param name="id">Quote id which will be deleted</param>
+    /// <response code="204">Returned on valid request</response>
+    /// <response code="404">Returned when no such quote exists</response>
     [HttpDelete("{id}")]
-    [ProducesResponseType(204)] 
-    [ProducesResponseType(typeof(ErrorDTO), 404)] 
     [Authorize]
     [EnableCors]
+    [ProducesResponseType(204)]
+    [ProducesResponseType(typeof(ErrorDTO), 404)]
     public async Task<IActionResult> DeleteQuote(int id)
     {
-        var quote = await _db.Quotes
+        // (Attempt to) find the quote
+        Quote? quote = await _db.Quotes
                             .FirstOrDefaultAsync(q => q.Id ==  id);
-        if(quote==null) return NotFound(new { status = "error", error_msg = "Quote not found" });
+        // Failed?
+        if (quote == null)
+            return NotFound(new { status = "error", error_msg = "Quote not found" });
+
+        // If succeded, remove the quote
         _db.Quotes.Remove(quote);
         await _db.SaveChangesAsync();
-        return Ok();
+
+        // ====================================================================== //
+        // Important!                                                             //
+        // Is this the best we can do? Won't marking the quote as "hidden"        //
+        // be better than explicitly deleting it? ~eee4                           //
+        // ====================================================================== //
+
+        // Return ok
+        return Ok(new { Status = "ok" });
     }
 
+    // PATCH /api/v1/quotes/{id}
+    /// <summary>
+    /// [AUTHED] Modify an existing quote
+    /// </summary>
+    /// <remarks>
+    /// Modifies an existing quote.
+    /// <br/><br/>
+    /// <b>Warning!</b>
+    /// We don't check the user id which created the quote.
+    /// In case of single-user instances, this should not be a problem.
+    /// This might become one, if we want users with non-admin roles;
+    /// that would need some proper ACL checks here (with the help of GUHF).
+    /// <br/><br/>
+    /// <b>Important!</b>
+    /// Image handling works the same as with creating new quote.
+    /// This means that images not present in the DB will be added automatically.
+    /// <br/><br/>
+    /// <b>Important!</b>
+    /// "categories = null" is not the same as "categories = []"!
+    /// While "categories = null" will not alter the quote's categories,
+    /// "categories = []" will (and in turn, empty each and every present category)!<br/>
+    /// Be careful when handling user-provided categories!
+    /// </remarks>
+    /// <returns>Newly modified quote as a DTO</returns>
+    /// <param name="id">Quote to be modified</param>
+    /// <param name="updatedQuote">Updated quote form data</param>
+    /// <response code="204">Returned on valid request</response>
+    /// <response code="400">Returned when request text or author is empty (or whitespace)</response>
+    /// <response code="404">Returned when no such quote exists</response>
     [HttpPatch("{id}")]
     [Authorize]
     [EnableCors]
     [ProducesResponseType(typeof(QuoteShortDTO), 200)]
     [ProducesResponseType(typeof(ErrorDTO), 400)]
     [ProducesResponseType(typeof(ErrorDTO), 404)]
-
     public async Task<IActionResult> EditQuote(int id, [FromBody] QuoteShortDTO updatedQuote)
     {
-        var Quote = await _db.Quotes
+        // Try to find the quote in question
+        Quote? quote = await _db.Quotes
             .Include(q => q.QuoteCategories)
-            // include image?
             .FirstOrDefaultAsync(q => q.Id == id);
 
-        if (Quote == null) return NotFound(new { status = "error", error_msg = "Quote not found" });
+        // Failed?
+        if (quote == null)
+            return NotFound(new { status = "error", error_msg = "Quote not found" });
+
+        // Is quote contents or author empty?
         if (string.IsNullOrWhiteSpace(updatedQuote.Text) || string.IsNullOrWhiteSpace(updatedQuote.Author))
-        {
             return BadRequest(new ErrorDTO { Status = "error", Error_msg = "Text and author are required." });
-        }
 
-        Quote.Text = updatedQuote.Text;
+        // Alter the quote's content
-        Quote.Author = updatedQuote.Author;
+        quote.Text = updatedQuote.Text;
-        Quote.LastUpdatedAt = DateTime.UtcNow;
+        quote.Author = updatedQuote.Author;
+        quote.LastUpdatedAt = DateTime.UtcNow;
 
+        // Try to find the image inside the DB
         Image? image = null;
         if (!string.IsNullOrEmpty(updatedQuote.ImageUrl))
         {
             image = await _db.Images.FirstOrDefaultAsync(i => i.Url == updatedQuote.ImageUrl);
+            // Failed? Just insert it yourself
             if (image == null)
             {
                 image = new Image { Url = updatedQuote.ImageUrl };
@@ -273,22 +333,29 @@ public class QuotesController : ControllerBase
                 await _db.SaveChangesAsync();
             }
         }
-        Quote.Image = image;
+        quote.Image = image;
 
+        // Don't touch categories if they are explicitly null
         if (updatedQuote.Categories == null) { }
+        // If they aren't
         else if (updatedQuote.Categories.Any())
         {
-            var categoriesFromDb = await _db.Categories
+            // Get all the categories associated with a quote from DB
+            List<Category> categoriesFromDb = await _db.Categories
                 .Where(c => updatedQuote.Categories.Contains(c.Name))
                 .ToListAsync();
 
-            // Dodaj nowe kategorie, których nie ma w bazie
+            // Determine which ones are already present, and which to add
-            var existingNames = categoriesFromDb
+            IEnumerable<string> existingNames = categoriesFromDb
                 .Select(c => c.Name);
-            var newNames = updatedQuote.Categories.Except(existingNames).ToList();
+            List<string> newNames = updatedQuote.Categories
+                .Except(existingNames)
+                .ToList();
 
+            // For all the categories not present
             foreach (var name in newNames)
             {
+                // Add them to the DB
                 var newCat = new Category {
                     Name = name,
                     Description = string.Empty,
@@ -298,25 +365,28 @@ public class QuotesController : ControllerBase
                 categoriesFromDb.Add(newCat);
             }
 
+            // If any categories were added, save changes
             if (newNames.Any())
                 await _db.SaveChangesAsync();
 
-            // Przypisz cytatowi nowe kategorie
+            // Assign all the new categories to the quote
-            Quote.QuoteCategories = categoriesFromDb
+            quote.QuoteCategories = categoriesFromDb
                 .Select(cat => new QuoteCategory {
                     CategoryId = cat.Id,
-                    QuoteId = Quote.Id
+                    QuoteId = quote.Id
                 })
                 .ToList();
         }
         else
         {
-            // Jeśli brak kategorii w dto, czyścić przypisane kategorie?
+            // No categories (empty list) inside DTO?
-            Quote.QuoteCategories.Clear();
+            // Clear them all!
+            quote.QuoteCategories.Clear();
         }
 
+        // Save changes, return new quote as a DTO
         await _db.SaveChangesAsync();
-        return Ok(Quote.ToQuoteShortDTO());
+        return Ok(quote.ToQuoteShortDTO());
     }
 
 }