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

DTOs/ErrorDTO.cs

@@ -0,0 +1,7 @@
+namespace QuotifyBE.DTOs;
+
+public record class ErrorDTO
+{
+    public string Status { get; set; }
+    public string Error_msg { get; set; }
+}

DTOs/QuoteShortDTO.cs

@@ -1,3 +1,5 @@
+namespace QuotifyBE.DTOs;
+
 public record class QuoteShortDTO
 {
     public int Id { get; set; }

Program.cs

@@ -1,8 +1,10 @@
 using Microsoft.AspNetCore.Authentication.JwtBearer;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.IdentityModel.Tokens;
+using Microsoft.OpenApi.Models;
 using QuotifyBE.Controllers;
 using QuotifyBE.Data;
+using System.Reflection;
 using System.Text;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -46,7 +48,29 @@ builder.Services.AddScoped<GeneralUseHelpers>();
 builder.Services.AddControllers();
 // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
 builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddSwaggerGen();
+builder.Services.AddSwaggerGen(options =>
+{
+    options.SwaggerDoc("v1", new OpenApiInfo
+    {
+        Version = "v1",
+        Title = "Quotify API",
+        Description = "An ASP.NET Core Web API for managing quotes",
+        Contact = new OpenApiContact
+        {
+            Name = "Quotify project's production branch",
+            Url = new Uri("https://quotify.7o7.cx")
+        },
+        License = new OpenApiLicense
+        {
+            Name = "AGPLv3",
+            Url = new Uri("https://www.gnu.org/licenses/agpl-3.0.en.html")
+        }
+    });
+
+    // using System.Reflection;
+    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
+});
 
 var app = builder.Build();
 

QuotifyBE.csproj

@@ -7,6 +7,8 @@
     <UserSecretsId>b302b0ab-745f-4b53-b32a-12fbbc3e622d</UserSecretsId>
     <DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
     <DockerfileContext>.</DockerfileContext>
+	<GenerateDocumentationFile>true</GenerateDocumentationFile>
+	<NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>
@@ -26,6 +28,7 @@
     <PackageReference Include="Npgsql" Version="9.0.3" />
     <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="9.0.4" />
     <PackageReference Include="Swashbuckle.AspNetCore" Version="9.0.3" />
+    <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="9.0.3" />
   </ItemGroup>
 
 </Project>

WeatherForecast.cs

@@ -1,13 +0,0 @@
-namespace QuotifyBE
-{
-    public class WeatherForecast
-    {
-        public DateOnly Date { get; set; }
-
-        public int TemperatureC { get; set; }
-
-        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
-
-        public string? Summary { get; set; }
-    }
-}