From a62923c8d677a281aeef02a89b19c4d69840ba24 Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Thu, 4 Dec 2025 14:07:17 +0100
Subject: [PATCH] Enhance OutResController with new features and docs

Added XML documentation to `OutResController` methods for clarity.
Introduced `ResultType` enum to specify result parts (Full, Header, Body).
Enhanced `Get` methods to support fake/test profiles and actions.
Added `[ProducesResponseType(StatusCodes.Status200OK)]` for explicit
response status codes. Updated `Get` overloads for various scenarios.
Utilized `config.GetFakeProfileId()` for dynamic fake profile handling.
---
 src/ReC.API/Controllers/OutResController.cs | 33 +++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/src/ReC.API/Controllers/OutResController.cs b/src/ReC.API/Controllers/OutResController.cs
index bef2d26..3f15be6 100644
--- a/src/ReC.API/Controllers/OutResController.cs
+++ b/src/ReC.API/Controllers/OutResController.cs
@@ -9,16 +9,37 @@ namespace ReC.API.Controllers;
 [ApiController]
 public class OutResController(IMediator mediator, IConfiguration config) : ControllerBase
 {
+    /// <summary>
+    /// Gets output results based on the provided query parameters.
+    /// </summary>
+    /// <param name="query">The query to filter output results.</param>
+    /// <param name="cancel">A token to cancel the operation.</param>
+    /// <returns>A list of output results matching the query.</returns>
     [HttpGet]
+    [ProducesResponseType(StatusCodes.Status200OK)]
     public async Task<IActionResult> Get([FromQuery] ReadOutResQuery query, CancellationToken cancel) => Ok(await mediator.Send(query, cancel));
 
+    /// <summary>
+    /// Gets output results for a fake/test profile.
+    /// </summary>
+    /// <param name="cancel">A token to cancel the operation.</param>
+    /// <returns>A list of output results for the fake profile.</returns>
     [HttpGet("fake")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
     public async Task<IActionResult> Get(CancellationToken cancel) => Ok(await mediator.Send(new ReadOutResQuery()
     {
         ProfileId = config.GetFakeProfileId()
     }, cancel));
 
+    /// <summary>
+    /// Gets a specific output result for a fake/test profile and action.
+    /// </summary>
+    /// <param name="actionId">The ID of the action to retrieve the result for.</param>
+    /// <param name="cancel">A token to cancel the operation.</param>
+    /// <param name="resultType">Specifies which part of the result to return (Full, Header, or Body).</param>
+    /// <returns>The requested output result or a part of it (header/body).</returns>
     [HttpGet("fake/{actionId}")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
     public async Task<IActionResult> Get([FromRoute] long actionId, CancellationToken cancel, ResultType resultType = ResultType.Full)
     {
         var res = (await mediator.Send(new ReadOutResQuery()
@@ -36,9 +57,21 @@ public class OutResController(IMediator mediator, IConfiguration config) : Contr
     }
 }
 
+/// <summary>
+/// Defines the type of result to be returned from an output result query.
+/// </summary>
 public enum ResultType
 {
+    /// <summary>
+    /// Return the full result object.
+    /// </summary>
     Full,
+    /// <summary>
+    /// Return only the header part of the result.
+    /// </summary>
     Header,
+    /// <summary>
+    /// Return only the body part of the result.
+    /// </summary>
     Body
 }