Add complete XML doc and Swagger annotations to all controller endpoints

Every public action now has <summary>, <param>, and <returns> XML docs
plus matching SwaggerOperation/SwaggerResponse attributes with typed response
descriptions. Class-level summaries added to CvController, JobSearchController,
and RagController. Explanatory inline comments removed from FileDownloadController
per project conventions.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Apis/rag-api/Controllers/RagController.cs

@@ -7,6 +7,10 @@ using Shared.Models.Responses;
 
 namespace Api.Controllers;
 
+/// <summary>
+/// Internal endpoints for indexing documents into the vector store and performing semantic search.
+/// Routes are prefixed with <c>api/rag</c>. Protected by the internal API key middleware — not reachable from the public internet.
+/// </summary>
 [ApiController]
 [Route("api/rag")]
 public sealed class RagController : ControllerBase
@@ -20,11 +24,22 @@ public sealed class RagController : ControllerBase
         _logger = logger;
     }
 
+    /// <summary>
+    /// Indexes a PDF file or plain-text document into the vector store via multipart/form-data.
+    /// Chunks the content, generates embeddings, and stores them for semantic retrieval.
+    /// Returns immediately from cache if an identical document was previously indexed.
+    /// </summary>
+    /// <param name="request">The indexing request: either a PDF file or raw text, plus optional title, source URL, and document type.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with an <see cref="IndexDocumentResponse"/> containing the document ID, chunk count, and cache status;
+    /// 400 Bad Request if neither a file nor text is provided, or the request is otherwise invalid.
+    /// </returns>
     [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")]
+    [SwaggerOperation(Summary = "Index document (multipart)", Description = "Indexes a PDF or plain-text document via multipart/form-data. Returns from cache if the same content was previously indexed.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Document indexed successfully", typeof(IndexDocumentResponse))]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Neither file nor text provided, or request is invalid", typeof(ErrorResponse))]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
     public async Task<ActionResult<IndexDocumentResponse>> IndexDocument(
@@ -62,10 +77,20 @@ public sealed class RagController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// Indexes a plain-text document sent as JSON into the vector store.
+    /// Returns immediately from cache if an identical document was previously indexed.
+    /// </summary>
+    /// <param name="request">The indexing request containing the raw text and optional title, source URL, and document type.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with an <see cref="IndexDocumentResponse"/> containing the document ID, chunk count, and cache status;
+    /// 400 Bad Request if the text is empty or the request is otherwise invalid.
+    /// </returns>
     [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")]
+    [SwaggerOperation(Summary = "Index document (JSON)", Description = "Indexes a plain-text document sent as JSON. Returns from cache if the same content was previously indexed.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Document indexed successfully", typeof(IndexDocumentResponse))]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Text missing or request invalid", typeof(ErrorResponse))]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
     public async Task<ActionResult<IndexDocumentResponse>> IndexJsonDocument([FromBody] IndexDocumentRequest request, CancellationToken ct)
@@ -86,10 +111,20 @@ public sealed class RagController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// Performs semantic (vector) search over indexed documents.
+    /// Embeds the query, retrieves the closest chunks by cosine similarity, and returns the ranked results.
+    /// </summary>
+    /// <param name="request">The search request: query text, optional document type filter, and maximum result count.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with a <see cref="SearchResponse"/> containing the ranked matching chunks with scores and metadata;
+    /// 400 Bad Request if the query is empty or the request is otherwise invalid.
+    /// </returns>
     [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")]
+    [SwaggerOperation(Summary = "Semantic search", Description = "Embeds the query and retrieves the closest document chunks by vector similarity.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Search results returned", typeof(SearchResponse))]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Query missing or request invalid", typeof(ErrorResponse))]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
     public async Task<ActionResult<SearchResponse>> Search([FromBody] SearchRequest request, CancellationToken ct)
@@ -109,10 +144,19 @@ public sealed class RagController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// Returns the stored details for a previously indexed document, including its extracted text and metadata.
+    /// </summary>
+    /// <param name="id">The document ID returned when the document was indexed.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with a <see cref="RagDocumentDetailsResponse"/> containing the document text and metadata;
+    /// 404 Not Found if no document with the given ID exists in the store.
+    /// </returns>
     [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")]
+    [SwaggerOperation(Summary = "Get document details", Description = "Returns the stored text and metadata for a previously indexed document.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Document details returned", typeof(RagDocumentDetailsResponse))]
+    [SwaggerResponse(StatusCodes.Status404NotFound, "Document not found", typeof(ErrorResponse))]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status404NotFound)]
     public async Task<ActionResult<RagDocumentDetailsResponse>> GetDocument(string id, CancellationToken ct)