chore: add API documentation to swagger

Controllers/AuthController.cs

@@ -10,6 +10,7 @@ namespace QuotifyBE.Controllers;
 
 [ApiController]
 [Route("api/v1/auth")]
+[Produces("application/json")]
 public class AuthController : ControllerBase
 {
 
@@ -25,7 +26,25 @@ public class AuthController : ControllerBase
     }
 
     // POST /api/v1/auth/login
+    /// <summary>
+    /// Log-in endpoint
+    /// </summary>
+    /// <remarks>
+    /// Allows to generate a JWT valid for 5 minutes.
+    /// The token needs to be passed to other, secured endpoints
+    /// in the Authorization header, e.g.: Authorization: bearer {jwt}
+    /// </remarks>
+    /// <param name="formUser">User's credentials (email and password)</param>
+    /// <returns>JWT valid for 5 minutes.</returns>
+    /// <response code="200">Returned on request with valid credentials</response>
+    /// <response code="400">Returned on request with missing form data (email, password or both)</response>
+    /// <response code="401">Returned on request with unknown pair of email and password (wrong password)</response>
+    /// <response code="404">Returned on request with unknwon email</response>
     [HttpPost("login")]
+    [ProducesResponseType(200)]
+    [ProducesResponseType(typeof(ErrorDTO), 400)]
+    [ProducesResponseType(typeof(ErrorDTO), 401)]
+    [ProducesResponseType(typeof(ErrorDTO), 404)]
     public async Task<IActionResult> Login([FromBody] UserLoginDTO formUser)
     {
         // Ensure the form is complete
@@ -52,8 +71,20 @@ public class AuthController : ControllerBase
     }
 
     // GET /api/v1/auth/some_values
+    /// <summary>
+    /// Dummy, authed endpoint
+    /// </summary>
+    /// <remarks>
+    /// Dummy, authed endpoint used to test JWTs.
+    /// Authed endpoints expect Authorization header, e.g.:
+    /// Authorization: bearer {jwt}</remarks>
+    /// <returns>Dummy json</returns>
+    /// <response code="200">Returned on request with valid credentials</response>
+    /// <response code="401">Returned on request with invalid JWT</response>
     [HttpGet("some_values")]
     [Authorize]
+    [ProducesResponseType(200)]
+    [ProducesResponseType(401)]
     public IActionResult GetValues()
     {
         return Ok(new string[] { "value1", "value2" });

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();