AI/myAi
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Add complete XML doc and Swagger annotations to all controller endpoints

Browse Source 
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>
This commit is contained in:
claude
2026-05-22 20:47:47 +03:00
parent 6deb8dd4c8
commit 1fcf1e1470
7 changed files with 192 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Apis/cv-matcher-api/Controllers/CvController.cs
+43 -9
View File
@@ -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)
Apis/cv-matcher-api/Controllers/JobSearchController.cs
+41
View File
@@ -3,9 +3,14 @@ using CvMatcher.Models.Requests;
using CvMatcher.Models.Responses;
using Microsoft.AspNetCore.Mvc;
using Shared.Models.Responses;
using Swashbuckle.AspNetCore.Annotations;
namespace Api.Controllers;
/// <summary>
/// Internal endpoints for managing one-click job-search tokens and sessions.
/// Routes are prefixed with <c>api/cv/job-search</c>. Protected by the internal API key middleware — not reachable from the public internet.
/// </summary>
[ApiController]
[Route("api/cv/job-search")]
public sealed class JobSearchController : ControllerBase
@@ -19,7 +24,26 @@ public sealed class JobSearchController : ControllerBase
_logger = logger;
}
/// <summary>
/// Creates a one-time job-search token linked to a CV document and email address.
/// Called by <c>api</c> immediately after a successful CV match when an email is provided.
/// The token is embedded in the job-search link sent to the user's email.
/// </summary>
/// <param name="request">The CV document ID and the recipient email address.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>
/// 200 OK with a <see cref="CreateJobSearchTokenResponse"/> containing the generated token ID;
/// 400 Bad Request if <c>CvDocumentId</c> or <c>Email</c> is missing;
/// 500 Internal Server Error if token creation fails.
/// </returns>
[HttpPost("token")]
[SwaggerOperation(Summary = "Create job search token", Description = "Creates a one-time token that lets the user start a background job search by clicking the link in their match email.")]
[SwaggerResponse(StatusCodes.Status200OK, "Token created successfully", typeof(CreateJobSearchTokenResponse))]
[SwaggerResponse(StatusCodes.Status400BadRequest, "CvDocumentId or Email missing", typeof(ErrorResponse))]
[SwaggerResponse(StatusCodes.Status500InternalServerError, "Token creation failed", typeof(ErrorResponse))]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status500InternalServerError)]
public async Task<ActionResult<CreateJobSearchTokenResponse>> CreateToken(
[FromBody] CreateJobSearchTokenRequest request,
CancellationToken ct)
@@ -39,7 +63,24 @@ public sealed class JobSearchController : ControllerBase
}
}
/// <summary>
/// Validates the one-time token, marks it as used, and enqueues a <c>JobSearchSession</c> with status <c>Pending</c>.
/// Called by <c>api</c> when the user clicks the job-search link in their match email.
/// The <c>cv-search-job</c> worker picks up the pending session and runs the search.
/// </summary>
/// <param name="tokenId">The UUID token extracted from the email link.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>
/// 200 OK with a <see cref="StartJobSearchResponse"/> whose <c>Status</c> is one of
/// <c>Started</c>, <c>AlreadyUsed</c>, or <c>Expired</c>;
/// 500 Internal Server Error if the session cannot be created.
/// </returns>
[HttpPost("token/{tokenId}/start")]
[SwaggerOperation(Summary = "Start job search", Description = "Validates the one-time token and creates a Pending job search session for the cv-search-job worker to process.")]
[SwaggerResponse(StatusCodes.Status200OK, "Search status returned (Started, AlreadyUsed, or Expired)", typeof(StartJobSearchResponse))]
[SwaggerResponse(StatusCodes.Status500InternalServerError, "Session creation failed", typeof(ErrorResponse))]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status500InternalServerError)]
public async Task<ActionResult<StartJobSearchResponse>> Start(string tokenId, CancellationToken ct)
{
try