From be0fe9d405ebf72526996e294de435f3a24e0b78 Mon Sep 17 00:00:00 2001 From: Aaron Po Date: Tue, 4 Aug 2026 06:18:01 -0400 Subject: [PATCH] update api docs --- .../JwtAuthenticationHandler.cs | 18 +----- .../Controllers/NotFoundController.cs | 5 -- .../Controllers/ProtectedController.cs | 8 +-- web/backend/API/API.Core/GlobalException.cs | 60 ++----------------- .../API/API.Specs/Mocks/MockEmailProvider.cs | 3 +- 5 files changed, 10 insertions(+), 84 deletions(-) diff --git a/web/backend/API/API.Core/Authentication/JwtAuthenticationHandler.cs b/web/backend/API/API.Core/Authentication/JwtAuthenticationHandler.cs index 539c9039..3e989b8d 100644 --- a/web/backend/API/API.Core/Authentication/JwtAuthenticationHandler.cs +++ b/web/backend/API/API.Core/Authentication/JwtAuthenticationHandler.cs @@ -12,11 +12,6 @@ namespace API.Core.Authentication; /// Custom ASP.NET Core authentication handler that validates bearer JWT access tokens /// supplied in the Authorization header against the JWT authentication scheme. /// -/// The monitored options for the JWT authentication scheme. -/// The logger factory used by the base . -/// The URL encoder used by the base . -/// The infrastructure service used to validate JWT access tokens. -/// The application configuration, used as a fallback source for the JWT secret key. public class JwtAuthenticationHandler( IOptionsMonitor options, ILoggerFactory logger, @@ -31,15 +26,9 @@ public class JwtAuthenticationHandler( /// /// The signing secret is resolved first from the ACCESS_TOKEN_SECRET environment variable, falling /// back to the Jwt:SecretKey configuration value, to stay consistent with the secret source used - /// when tokens are issued. Authentication fails if the secret is not configured, the - /// Authorization header is missing, the header does not use the Bearer scheme, or the - /// token fails validation. + /// when tokens are issued. Fails if the secret is not configured, the Authorization header is + /// missing or not Bearer-scheme, or the token fails validation. /// - /// - /// A successful containing the validated - /// - /// on success, or a failure result describing why authentication could not be completed. - /// protected override async Task HandleAuthenticateAsync() { // Use the same access-token secret source as TokenService to avoid mismatched validation. @@ -78,8 +67,6 @@ public class JwtAuthenticationHandler( /// /// Writes a JSON 401 Unauthorized response when authentication fails or is required but not supplied. /// - /// The authentication properties associated with the challenge. - /// A task that completes once the response body has been written. protected override async Task HandleChallengeAsync(AuthenticationProperties properties) { Response.ContentType = "application/json"; @@ -96,5 +83,4 @@ public class JwtAuthenticationHandler( /// /// Options for the JWT authentication scheme handled by . /// -/// No additional options are defined beyond those provided by . public class JwtAuthenticationOptions : AuthenticationSchemeOptions { } diff --git a/web/backend/API/API.Core/Controllers/NotFoundController.cs b/web/backend/API/API.Core/Controllers/NotFoundController.cs index 35c38903..58a1a8af 100644 --- a/web/backend/API/API.Core/Controllers/NotFoundController.cs +++ b/web/backend/API/API.Core/Controllers/NotFoundController.cs @@ -6,7 +6,6 @@ namespace API.Core.Controllers; /// Handles requests that do not match any other route, used as the application's fallback controller. /// /// -/// Excluded from API explorer/Swagger output via [ApiExplorerSettings(IgnoreApi = true)]. /// Wired up as the fallback target via app.MapFallbackToController("Handle404", "NotFound") in /// Program.cs. /// @@ -15,10 +14,6 @@ namespace API.Core.Controllers; [Route("error")] // required public class NotFoundController : ControllerBase { - /// - /// Returns a generic 404 response for any request that did not match a defined route. - /// - /// A 404 Not Found result with a JSON body containing a "Route not found." message. [HttpGet("404")] //required public IActionResult Handle404() { diff --git a/web/backend/API/API.Core/Controllers/ProtectedController.cs b/web/backend/API/API.Core/Controllers/ProtectedController.cs index 02199d4f..a88e8e0f 100644 --- a/web/backend/API/API.Core/Controllers/ProtectedController.cs +++ b/web/backend/API/API.Core/Controllers/ProtectedController.cs @@ -14,13 +14,9 @@ namespace API.Core.Controllers; public class ProtectedController : ControllerBase { /// - /// Returns the authenticated caller's user ID and username, extracted from the JWT claims. + /// Returns the authenticated caller's user ID and username extracted from the JWT claims. /// - /// - /// A 200 OK result wrapping a whose payload contains the - /// caller's userId (from ) and username - /// (from ), either of which may be null if not present in the token. - /// + /// userId and username may be null if not present in the token. [HttpGet] public ActionResult> Get() { diff --git a/web/backend/API/API.Core/GlobalException.cs b/web/backend/API/API.Core/GlobalException.cs index ae37dc6a..d9fd376e 100644 --- a/web/backend/API/API.Core/GlobalException.cs +++ b/web/backend/API/API.Core/GlobalException.cs @@ -13,67 +13,17 @@ namespace API.Core; /// MVC exception filter that converts unhandled exceptions raised by controller actions into /// consistent JSON error responses with appropriate HTTP status codes. /// -/// Logger used to record unhandled exceptions before they are translated into a response. public class GlobalExceptionFilter(ILogger logger) : IExceptionFilter { /// - /// Logs the exception and sets to an appropriate error response, - /// marking the exception as handled. + /// Logs the exception and sets to an appropriate error response. /// /// - /// Maps exception types to responses as follows: - /// - /// - /// - /// → 400 Bad Request with per-property - /// validation error messages. - /// - /// - /// - /// - /// → 409 Conflict with a - /// message. - /// - /// - /// - /// - /// → 404 Not Found with a - /// message. - /// - /// - /// - /// - /// → 401 Unauthorized with a - /// message. - /// - /// - /// - /// - /// → 403 Forbidden with a - /// message. - /// - /// - /// - /// - /// → 503 Service Unavailable with a generic database error - /// message. - /// - /// - /// - /// - /// → 400 Bad Request with a - /// message. - /// - /// - /// - /// Any other exception → 500 Internal Server Error with a generic error message. - /// - /// + /// Maps to 400, to 409, + /// to 404, to 401, + /// to 403, to 503, + /// to 400, and anything else to 500. /// - /// - /// The context for the unhandled exception, including the exception itself and the result to - /// populate. - /// public void OnException(ExceptionContext context) { logger.LogError(context.Exception, "Unhandled exception occurred"); diff --git a/web/backend/API/API.Specs/Mocks/MockEmailProvider.cs b/web/backend/API/API.Specs/Mocks/MockEmailProvider.cs index 6d598338..54ba74b3 100644 --- a/web/backend/API/API.Specs/Mocks/MockEmailProvider.cs +++ b/web/backend/API/API.Specs/Mocks/MockEmailProvider.cs @@ -3,8 +3,7 @@ using Infrastructure.Email; namespace API.Specs.Mocks; /// -/// Mock email provider for testing that doesn't actually send emails. -/// Tracks sent emails for verification in tests if needed. +/// Test double for that records sent emails instead of delivering them. /// public class MockEmailProvider : IEmailProvider {