chore: add API documentation to swagger

Controllers/QuoteController.cs

@@ -1,6 +1,7 @@
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Authorization;
 using QuotifyBE.Data;
+using QuotifyBE.DTOs;
 using QuotifyBE.Entities;
 using QuotifyBE.Mapping;
 using System.Security.Claims;
@@ -11,6 +12,7 @@ namespace QuotifyBE.Controllers;
 
 [ApiController]
 [Route("api/v1/quotes")]
+[Produces("application/json")]
 public class QuotesController : ControllerBase
 {
 
@@ -25,9 +27,16 @@ public class QuotesController : ControllerBase
 
     // GET /api/v1/quotes
     /// <summary>
-    /// Get a given quote page
+    /// Get a page of quotes
     /// </summary>
+    /// <remarks>A page of quotes consists of 10 quotes or less. If a page does not contain any quotes, 404 is returned.</remarks>
+    /// <param name="page_no">The page number</param>
+    /// <returns>A page (10 quotes)</returns>
+    /// <response code="200">Returned on valid request</response>
+    /// <response code="404">Returned when requested page is invalid or does not exist</response>
     [HttpGet("page/{page_no}")]
+    [ProducesResponseType(typeof(List<QuoteShortDTO>), 200)]
+    [ProducesResponseType(typeof(ErrorDTO), 404)]
     public async Task<IActionResult> GetQuotePage(int page_no)
     {
         // TODO...
@@ -38,10 +47,19 @@ public class QuotesController : ControllerBase
     }
 
     // GET /api/v1/quotes/{id}
+    /// <summary>
+    /// 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>
+    /// <response code="200">Returned on valid request</response>
+    /// <response code="404">Returned when quote id is invalid or simply doesn't exist</response>
     [HttpGet("{id}")]
+    [ProducesResponseType(typeof(QuoteShortDTO), 200)]
+    [ProducesResponseType(typeof(ErrorDTO), 404)]
     public async Task<IActionResult> GetQuoteById(int id)
     {
-        // FIXME: The expression 'q.QuoteCategories' is invalid inside an 'Include' operation, since it does not represent a property access: 't => t.MyProperty'.
+
         var quote = await _db.Quotes
             .Include(q => q.QuoteCategories!)
             .ThenInclude(qc => qc.Category)
@@ -56,8 +74,19 @@ public class QuotesController : ControllerBase
     }
 
     // POST /api/v1/quotes/new
+    /// <summary>
+    /// Add a new quote
+    /// </summary>
+    /// <returns>Newly created quote's id</returns>
+    /// <param name="request">Form data containing required quote information</param>
+    /// <response code="201">Returned on valid request</response>
+    /// <response code="400">Returned when any of the categories does not exist</response>
+    /// <response code="401">Returned when user's id does not match the creator's id</response>
     [HttpPost("new")]
     [Authorize]
+    [ProducesResponseType(201)] // ?
+    [ProducesResponseType(typeof(ErrorDTO), 400)]
+    [ProducesResponseType(typeof(ErrorDTO), 401)]
     public async Task<IActionResult> CreateQuote([FromBody] CreateQuoteDTO request)
     {
         // Get user ID from claims
@@ -111,8 +140,16 @@ public class QuotesController : ControllerBase
     }
 
     // GET /api/v1/quotes/random
+    /// <summary>
+    /// Get a random quote summary
+    /// </summary>
+    /// <returns>A quote: id, quote content and author, imageUrl and categories if successful, otherwise: error message</returns>
+    /// <response code="200">Returned on valid request</response>
+    /// <response code="404">Returned when no quotes exist</response>
     [HttpGet("random")]
     [AllowAnonymous]
+    [ProducesResponseType(typeof(QuoteShortDTO), 200)]
+    [ProducesResponseType(typeof(ErrorDTO), 404)]
     public async Task<IActionResult> GetRandomQuote()
     {
         var totalQuotes = await _db.Quotes.CountAsync();