From 441f04790659a439c0054b7b06130d14cc2eb90b Mon Sep 17 00:00:00 2001
From: transtrike <transtrike@gmail.com>
Date: Sat, 13 Mar 2021 10:01:23 +0200
Subject: Technology xml comments added; Needs finish

---
 .../Controllers/TechnologyController.cs            |  5 +++
 src/Web/DevHive.Web/Controllers/UserController.cs  | 52 ++++++++++++++++++++--
 2 files changed, 54 insertions(+), 3 deletions(-)

(limited to 'src/Web/DevHive.Web/Controllers')

diff --git a/src/Web/DevHive.Web/Controllers/TechnologyController.cs b/src/Web/DevHive.Web/Controllers/TechnologyController.cs
index e507899..ba3f04a 100644
--- a/src/Web/DevHive.Web/Controllers/TechnologyController.cs
+++ b/src/Web/DevHive.Web/Controllers/TechnologyController.cs
@@ -23,6 +23,11 @@ namespace DevHive.Web.Controllers
 			this._technologyMapper = technologyMapper;
 		}
 
+		/// <summary>
+		/// Create a new technology, so users can have a choice. Admin only!
+		/// </summary>
+		/// <param name="createTechnologyWebModel">Data for the new technology</param>
+		/// <returns></returns>
 		[HttpPost]
 		[Authorize(Roles = "Admin")]
 		public async Task<IActionResult> Create([FromBody] CreateTechnologyWebModel createTechnologyWebModel)
diff --git a/src/Web/DevHive.Web/Controllers/UserController.cs b/src/Web/DevHive.Web/Controllers/UserController.cs
index b01ecc1..86076e5 100644
--- a/src/Web/DevHive.Web/Controllers/UserController.cs
+++ b/src/Web/DevHive.Web/Controllers/UserController.cs
@@ -8,12 +8,16 @@ using Microsoft.AspNetCore.Mvc;
 using DevHive.Common.Models.Identity;
 using DevHive.Services.Interfaces;
 using DevHive.Common.Jwt.Interfaces;
-using DevHive.Web.Models.Attributes;
+using NSwag.Annotations;
 
 namespace DevHive.Web.Controllers
 {
+	/// <summary>
+	/// All endpoints for integration with the User
+	/// </summary>
 	[ApiController]
 	[Route("/api/[controller]")]
+	[OpenApiController("User Controller")]
 	public class UserController : ControllerBase
 	{
 		private readonly IUserService _userService;
@@ -28,9 +32,15 @@ namespace DevHive.Web.Controllers
 		}
 
 		#region Authentication
+		/// <summary>
+		/// Login endpoint for the DevHive Social Platform
+		/// </summary>
+		/// <param name="loginModel">Login model with username and password</param>
+		/// <returns>A JWT Token for further validation</returns>
 		[HttpPost]
-		[Route("Login")]
 		[AllowAnonymous]
+		[Route("Login")]
+		[OpenApiTags("Authorization")]
 		public async Task<IActionResult> Login([FromBody] LoginWebModel loginModel)
 		{
 			LoginServiceModel loginServiceModel = this._userMapper.Map<LoginServiceModel>(loginModel);
@@ -41,9 +51,15 @@ namespace DevHive.Web.Controllers
 			return new OkObjectResult(tokenWebModel);
 		}
 
+		/// <summary>
+		/// Register a new User in the DevHive Social Platform
+		/// </summary>
+		/// <param name="registerModel">Register model with the new data to provide</param>
+		/// <returns>A JWT Token for further validation</returns>
 		[HttpPost]
-		[Route("Register")]
 		[AllowAnonymous]
+		[Route("Register")]
+		[OpenApiTag("Authorization")]
 		public async Task<IActionResult> Register([FromBody] RegisterWebModel registerModel)
 		{
 			RegisterServiceModel registerServiceModel = this._userMapper.Map<RegisterServiceModel>(registerModel);
@@ -56,6 +72,12 @@ namespace DevHive.Web.Controllers
 		#endregion
 
 		#region Read
+		/// <summary>
+		/// Get a User's information using the Guid
+		/// </summary>
+		/// <param name="id">User's Guid</param>
+		/// <param name="authorization">The JWT Token, contained in the header and used for validation</param>
+		/// <returns>A full User's read model</returns>
 		[HttpGet]
 		[Authorize(Roles = "User,Admin")]
 		public async Task<IActionResult> GetById(Guid id, [FromHeader] string authorization)
@@ -69,6 +91,11 @@ namespace DevHive.Web.Controllers
 			return new OkObjectResult(userWebModel);
 		}
 
+		/// <summary>
+		/// Get a User's profile using his username. Does NOT require authorization
+		/// </summary>
+		/// <param name="username">User's username</param>
+		/// <returns>A trimmed version of the full User's read model</returns>
 		[HttpGet]
 		[Route("GetUser")]
 		[AllowAnonymous]
@@ -82,6 +109,13 @@ namespace DevHive.Web.Controllers
 		#endregion
 
 		#region Update
+		/// <summary>
+		/// Full update on User's data. A PUSTINQK can only edit his account
+		/// </summary>
+		/// <param name="id">The User's Guid</param>
+		/// <param name="updateUserWebModel">A full User update model</param>
+		/// <param name="authorization">The JWT Token, contained in the header and used for validation</param>
+		/// <returns>A full User's read model</returns>
 		[HttpPut]
 		[Authorize(Roles = "User,Admin")]
 		public async Task<IActionResult> Update(Guid id, [FromBody] UpdateUserWebModel updateUserWebModel, [FromHeader] string authorization)
@@ -100,6 +134,12 @@ namespace DevHive.Web.Controllers
 		#endregion
 
 		#region Delete
+		/// <summary>
+		/// Delete a User with his Id. A PUSTINQK can only delete his account. An Admin can delete all accounts
+		/// </summary>
+		/// <param name="id">The User's Guid</param>
+		/// <param name="authorization">The JWT Token, contained in the header and used for validation</param>
+		/// <returns>Ok, BadRequest or Unauthorized</returns>
 		[HttpDelete]
 		[Authorize(Roles = "User,Admin")]
 		public async Task<IActionResult> Delete(Guid id, [FromHeader] string authorization)
@@ -115,7 +155,13 @@ namespace DevHive.Web.Controllers
 		}
 		#endregion
 
+		/// <summary>
+		/// We don't talk about that, NIGGA!
+		/// </summary>
+		/// <param name="userId"></param>
+		/// <returns></returns>
 		[HttpPost]
+		[OpenApiIgnore]
 		[Authorize(Roles = "User,Admin")]
 		[Route("SuperSecretPromotionToAdmin")]
 		public async Task<IActionResult> SuperSecretPromotionToAdmin(Guid userId)
-- 
cgit v1.2.3