From 9f6407261bea4ad11f4e1c4b30b642d02232bd18 Mon Sep 17 00:00:00 2001
From: jvyden <jvyden@jvyden.xyz>
Date: Tue, 1 Feb 2022 00:34:22 -0500
Subject: [PATCH] Add api documentation to swagger

---
 .../Controllers/Api/SlotEndpoints.cs          | 21 +++++++++++++++++++
 .../Controllers/Api/StatisticsEndpoints.cs    | 11 +++++++++-
 .../Controllers/Api/UserEndpoints.cs          | 13 ++++++++++++
 ProjectLighthouse/Startup/Startup.cs          |  9 ++++++++
 4 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/ProjectLighthouse/Controllers/Api/SlotEndpoints.cs b/ProjectLighthouse/Controllers/Api/SlotEndpoints.cs
index 23a70fe2..909f9a95 100644
--- a/ProjectLighthouse/Controllers/Api/SlotEndpoints.cs
+++ b/ProjectLighthouse/Controllers/Api/SlotEndpoints.cs
@@ -5,11 +5,15 @@ using System.Threading.Tasks;
 using LBPUnion.ProjectLighthouse.Types;
 using LBPUnion.ProjectLighthouse.Types.Levels;
 using LBPUnion.ProjectLighthouse.Types.Settings;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.EntityFrameworkCore;
 
 namespace LBPUnion.ProjectLighthouse.Controllers.Api;
 
+/// <summary>
+/// A collection of endpoints relating to slots.
+/// </summary>
 public class SlotEndpoints : ApiEndpointController
 {
     private readonly Database database;
@@ -19,7 +23,15 @@ public class SlotEndpoints : ApiEndpointController
         this.database = database;
     }
 
+    /// <summary>
+    /// Gets a list of (stripped down) slots from the database.
+    /// </summary>
+    /// <param name="limit">How many slots you want to retrieve.</param>
+    /// <param name="skip">How many slots to skip.</param>
+    /// <returns>The slot</returns>
+    /// <response code="200">The slot list, if successful.</response>
     [HttpGet("slots")]
+    [ProducesResponseType(typeof(List<MinimalSlot>), StatusCodes.Status200OK)]
     public async Task<IActionResult> GetSlots([FromQuery] int limit = 20, [FromQuery] int skip = 0)
     {
         limit = Math.Min(ServerStatics.PageSize, limit);
@@ -30,7 +42,16 @@ public class SlotEndpoints : ApiEndpointController
         return this.Ok(minimalSlots);
     }
 
+    /// <summary>
+    /// Gets a slot (more commonly known as a level) and its information from the database.
+    /// </summary>
+    /// <param name="id">The ID of the slot</param>
+    /// <returns>The slot</returns>
+    /// <response code="200">The slot, if successful.</response>
+    /// <response code="404">The slot could not be found.</response>
     [HttpGet("slot/{id:int}")]
+    [ProducesResponseType(typeof(Slot), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetSlot(int id)
     {
         Slot? slot = await this.database.Slots.FirstOrDefaultAsync(u => u.SlotId == id);
diff --git a/ProjectLighthouse/Controllers/Api/StatisticsEndpoints.cs b/ProjectLighthouse/Controllers/Api/StatisticsEndpoints.cs
index b21f4b6e..a89828ac 100644
--- a/ProjectLighthouse/Controllers/Api/StatisticsEndpoints.cs
+++ b/ProjectLighthouse/Controllers/Api/StatisticsEndpoints.cs
@@ -2,14 +2,23 @@ using System.Threading.Tasks;
 using LBPUnion.ProjectLighthouse.Helpers;
 using LBPUnion.ProjectLighthouse.Types;
 using LBPUnion.ProjectLighthouse.Types.Api;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 
 namespace LBPUnion.ProjectLighthouse.Controllers.Api;
 
+/// <summary>
+/// A collection of endpoints relating to statistics.
+/// </summary>
 public class StatisticsEndpoints : ApiEndpointController
 {
+    /// <summary>
+    /// Gets everything that StatisticsHelper provides.
+    /// </summary>
+    /// <returns>An instance of StatisticsResponse</returns>
     [HttpGet("statistics")]
-    public async Task<IActionResult> OnGet()
+    [ProducesResponseType(typeof(StatisticsResponse), StatusCodes.Status200OK)]
+    public async Task<IActionResult> GetStatistics()
         => this.Ok
         (
             new StatisticsResponse
diff --git a/ProjectLighthouse/Controllers/Api/UserEndpoints.cs b/ProjectLighthouse/Controllers/Api/UserEndpoints.cs
index 0f2ebafb..7fc505eb 100644
--- a/ProjectLighthouse/Controllers/Api/UserEndpoints.cs
+++ b/ProjectLighthouse/Controllers/Api/UserEndpoints.cs
@@ -1,11 +1,15 @@
 #nullable enable
 using System.Threading.Tasks;
 using LBPUnion.ProjectLighthouse.Types;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.EntityFrameworkCore;
 
 namespace LBPUnion.ProjectLighthouse.Controllers.Api;
 
+/// <summary>
+/// A collection of endpoints relating to users.
+/// </summary>
 public class UserEndpoints : ApiEndpointController
 {
     private readonly Database database;
@@ -15,7 +19,16 @@ public class UserEndpoints : ApiEndpointController
         this.database = database;
     }
 
+    /// <summary>
+    /// Gets a user and their information from the database.
+    /// </summary>
+    /// <param name="id">The ID of the user</param>
+    /// <returns>The user</returns>
+    /// <response code="200">The user, if successful.</response>
+    /// <response code="404">The user could not be found.</response>
     [HttpGet("user/{id:int}")]
+    [ProducesResponseType(typeof(User), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetUser(int id)
     {
         User? user = await this.database.Users.FirstOrDefaultAsync(u => u.UserId == id);
diff --git a/ProjectLighthouse/Startup/Startup.cs b/ProjectLighthouse/Startup/Startup.cs
index bf428bde..fed0488a 100644
--- a/ProjectLighthouse/Startup/Startup.cs
+++ b/ProjectLighthouse/Startup/Startup.cs
@@ -1,5 +1,7 @@
+using System;
 using System.Diagnostics;
 using System.IO;
+using System.Reflection;
 using Kettu;
 using LBPUnion.ProjectLighthouse.Helpers;
 using LBPUnion.ProjectLighthouse.Logging;
@@ -60,6 +62,7 @@ public class Startup
         (
             c =>
             {
+                // Give swagger the name and version of our project
                 c.SwaggerDoc
                 (
                     "v1",
@@ -69,7 +72,13 @@ public class Startup
                         Version = "v1",
                     }
                 );
+
+                // Filter out endpoints not in /api/v1
                 c.DocumentFilter<SwaggerFilter>();
+
+                // Add XMLDoc to swagger
+                string xmlDocs = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlDocs));
             }
         );