Comments

rag-api/Controllers/HealthController.cs

@@ -1,4 +1,5 @@
 using Microsoft.AspNetCore.Mvc;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace Api.Controllers
 {
@@ -19,6 +20,9 @@ namespace Api.Controllers
         /// </returns>
         // GET api/health/live
         [HttpGet("live")]
+        [SwaggerOperation(Summary = "Liveness probe", Description = "Returns whether the API process is alive.")]
+        [SwaggerResponse(StatusCodes.Status200OK, "Service is alive")]
+        [ProducesResponseType(StatusCodes.Status200OK)]
         public IActionResult Live() => Ok(new { status = "alive" });
 
         /// <summary>
@@ -30,6 +34,9 @@ namespace Api.Controllers
         /// </returns>
         // GET api/health
         [HttpGet]
+        [SwaggerOperation(Summary = "Health check", Description = "Returns overall health status and current UTC time.")]
+        [SwaggerResponse(StatusCodes.Status200OK, "Health check succeeded")]
+        [ProducesResponseType(StatusCodes.Status200OK)]
         public IActionResult Health() => Ok(new { status = "ok", time = DateTimeOffset.UtcNow });
 
         /// <summary>
@@ -40,6 +47,9 @@ namespace Api.Controllers
         /// <returns>200 OK with the same JSON payload provided in the request body.</returns>
         // POST api/health/echo
         [HttpPost("echo")]
+        [SwaggerOperation(Summary = "Echo payload", Description = "Returns the same JSON payload received in the request body.")]
+        [SwaggerResponse(StatusCodes.Status200OK, "Payload echoed successfully")]
+        [ProducesResponseType(StatusCodes.Status200OK)]
         public IActionResult Echo(object payload) => Ok(payload);
 
         /// <summary>
@@ -52,6 +62,11 @@ namespace Api.Controllers
         /// </returns>
         // GET api/health/ready
         [HttpGet("ready")]
+        [SwaggerOperation(Summary = "Readiness probe", Description = "Returns whether the service is ready to accept traffic.")]
+        [SwaggerResponse(StatusCodes.Status200OK, "Service is ready")]
+        [SwaggerResponse(StatusCodes.Status503ServiceUnavailable, "Service is not ready")]
+        [ProducesResponseType(StatusCodes.Status200OK)]
+        [ProducesResponseType(StatusCodes.Status503ServiceUnavailable)]
         public IActionResult Ready()
         {
             var ready = true;

rag-api/Controllers/RagController.cs

@@ -2,6 +2,7 @@ using Microsoft.AspNetCore.Mvc;
 using Api.Services.Contracts;
 using Rag.Models.Requests;
 using Rag.Models.Responses;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace Api.Controllers;
 
@@ -20,6 +21,11 @@ public sealed class RagController : ControllerBase
 
     [HttpPost("documents")]
     [RequestSizeLimit(10 * 1024 * 1024)]
+    [SwaggerOperation(Summary = "Index document (multipart)", Description = "Indexes a PDF file or raw text document using multipart/form-data payload.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Document indexed successfully")]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid indexing request")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
     public async Task<ActionResult<IndexDocumentResponse>> IndexDocument(
         [FromForm] IndexDocumentUploadRequest request,
         CancellationToken ct)
@@ -56,6 +62,11 @@ public sealed class RagController : ControllerBase
     }
 
     [HttpPost("documents/json")]
+    [SwaggerOperation(Summary = "Index document (JSON)", Description = "Indexes a text document sent as JSON.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "JSON document indexed successfully")]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid JSON indexing request")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
     public async Task<ActionResult<IndexDocumentResponse>> IndexJsonDocument([FromBody] IndexDocumentRequest request, CancellationToken ct)
     {
         try
@@ -75,6 +86,11 @@ public sealed class RagController : ControllerBase
     }
 
     [HttpPost("search")]
+    [SwaggerOperation(Summary = "Semantic search", Description = "Performs semantic retrieval over indexed documents.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Search results returned")]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid search request")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
     public async Task<ActionResult<SearchResponse>> Search([FromBody] SearchRequest request, CancellationToken ct)
     {
         try
@@ -93,6 +109,11 @@ public sealed class RagController : ControllerBase
     }
 
     [HttpGet("documents/{id}")]
+    [SwaggerOperation(Summary = "Get document details", Description = "Returns indexed document details for the provided document id.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Document details returned")]
+    [SwaggerResponse(StatusCodes.Status404NotFound, "Document was not found")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<ActionResult<RagDocumentDetailsResponse>> GetDocument(string id, CancellationToken ct)
     {
         _logger.LogInformation("Get document request received. DocumentId={DocumentId}", id);