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/cv-matcher-api/Controllers/CvController.cs

@@ -8,6 +8,10 @@ using Shared.Models.Responses;
 
 namespace Api.Controllers;
 
+/// <summary>
+/// Internal endpoints for CV indexing and job-matching operations.
+/// Routes are prefixed with <c>api/cv</c>. Protected by the internal API key middleware — not reachable from the public internet.
+/// </summary>
 [ApiController]
 [Route("api/cv")]
 public sealed class CvController : ControllerBase
@@ -21,11 +25,21 @@ public sealed class CvController : ControllerBase
         _logger = logger;
     }
 
+    /// <summary>
+    /// Uploads and indexes a CV PDF into the RAG vector store.
+    /// Returns from cache immediately if an identical document was previously indexed.
+    /// </summary>
+    /// <param name="request">Multipart form containing the CV PDF file.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with a <see cref="CvUploadResponse"/> containing the document ID and whether it was a cache hit;
+    /// 400 Bad Request if the file is missing or the request is otherwise invalid.
+    /// </returns>
     [HttpPost("upload")]
     [RequestSizeLimit(10 * 1024 * 1024)]
-    [SwaggerOperation(Summary = "Upload CV document", Description = "Uploads a CV PDF and indexes it for matching.")]
-    [SwaggerResponse(StatusCodes.Status200OK, "CV uploaded and indexed successfully")]
-    [SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid upload request")]
+    [SwaggerOperation(Summary = "Upload CV document", Description = "Uploads a CV PDF and indexes it into the RAG vector store. Returns from cache if the same document was previously uploaded.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "CV indexed successfully", typeof(CvUploadResponse))]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "File missing or request invalid", typeof(ErrorResponse))]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
     public async Task<ActionResult<CvUploadResponse>> Upload([FromForm] UploadFileRequest request, CancellationToken ct)
@@ -45,10 +59,19 @@ public sealed class CvController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// Returns the top matching job documents for a previously indexed CV using semantic vector search.
+    /// </summary>
+    /// <param name="request">The request containing the CV document ID and the maximum number of results to return.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with a <see cref="FindJobsResponse"/> containing the ranked list of matching jobs;
+    /// 400 Bad Request if the CV document ID is missing or invalid.
+    /// </returns>
     [HttpPost("find-jobs")]
-    [SwaggerOperation(Summary = "Find matching jobs", Description = "Finds top matching jobs for a previously uploaded CV document.")]
-    [SwaggerResponse(StatusCodes.Status200OK, "Matching jobs returned")]
-    [SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid find jobs request")]
+    [SwaggerOperation(Summary = "Find matching jobs", Description = "Performs semantic search over indexed job documents to find the best matches for a given CV.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Matching jobs returned", typeof(FindJobsResponse))]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "CV document ID missing or invalid", typeof(ErrorResponse))]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
     public async Task<ActionResult<FindJobsResponse>> FindJobs([FromBody] FindJobsRequest request, CancellationToken ct)
@@ -67,10 +90,21 @@ public sealed class CvController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// Scores a CV against a single job using LLM analysis.
+    /// Fetches and extracts job text from the provided URL if no inline description is supplied,
+    /// then runs a deep semantic match and returns a score with strengths and gaps.
+    /// </summary>
+    /// <param name="request">The match request: CV document ID plus either a job URL or an inline job description.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with a <see cref="JobMatchResponse"/> containing the score (0–100), strengths, gaps, and cache status;
+    /// 400 Bad Request if required fields are missing or the request is invalid.
+    /// </returns>
     [HttpPost("match-job")]
-    [SwaggerOperation(Summary = "Match CV to one job", Description = "Computes detailed match analysis between a CV and a single job description or URL.")]
-    [SwaggerResponse(StatusCodes.Status200OK, "Job match computed successfully")]
-    [SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid match job request")]
+    [SwaggerOperation(Summary = "Match CV to one job", Description = "Scores a CV against a job URL or description using LLM analysis and returns a match score with strengths and gaps.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Job match computed successfully", typeof(JobMatchResponse))]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Required fields missing or request invalid", typeof(ErrorResponse))]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
     public async Task<ActionResult<JobMatchResponse>> MatchJob([FromBody] MatchJobRequest request, CancellationToken ct)