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>
This commit is contained in:
2026-05-22 20:47:47 +03:00
parent 6deb8dd4c8
commit 1fcf1e1470
7 changed files with 192 additions and 69 deletions
+13 -4
View File
@@ -29,8 +29,10 @@ namespace Api.Controllers
/// <summary>
/// Returns the public reCAPTCHA site key used by the client to render the widget.
/// </summary>
/// <returns>200 OK with the configured public site key as a plain string.</returns>
[HttpGet]
[SwaggerOperation(Summary = "Get captcha site key")]
[SwaggerOperation(Summary = "Get captcha public key", Description = "Returns the public reCAPTCHA site key required by the frontend to render the challenge widget.")]
[SwaggerResponse(StatusCodes.Status200OK, "Public site key returned")]
[ProducesResponseType(StatusCodes.Status200OK)]
public IActionResult GetSiteKey()
{
@@ -38,13 +40,20 @@ namespace Api.Controllers
}
/// <summary>
/// Verify a captcha token and return the verification verdict.
/// Verifies a reCAPTCHA token submitted by the client and returns the full verification verdict.
/// </summary>
/// <param name="req">The verification request containing the token and optional expected action name.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>
/// 200 OK with the full captcha verdict when verification passes;
/// 400 Bad Request with an <see cref="ErrorResponse"/> if the token is missing or verification fails.
/// </returns>
[HttpPost("verify")]
[SwaggerOperation(Summary = "Verify captcha token")]
[SwaggerOperation(Summary = "Verify captcha token", Description = "Verifies a reCAPTCHA token and returns the provider verdict including the score.")]
[SwaggerResponse(StatusCodes.Status200OK, "Token verified successfully")]
[SwaggerResponse(StatusCodes.Status400BadRequest, "Token missing or verification failed", typeof(ErrorResponse))]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
[SwaggerResponse(StatusCodes.Status400BadRequest, "Captcha verification failed or token missing", typeof(ErrorResponse))]
public async Task<IActionResult> Verify([FromBody] CaptchaVerifyRequest req, CancellationToken ct)
{
if (req is null || string.IsNullOrWhiteSpace(req.Token))