Merge pull request #393 from DFE-Digital/v1-keystage-documentation

V1 keystage documentation

TramsDataApi/Controllers/KeyStagePerformanceController.cs

@@ -2,14 +2,19 @@
 using System.Text.Json;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
+using Swashbuckle.AspNetCore.Annotations;
 using TramsDataApi.DatabaseModels;
 using TramsDataApi.ResponseModels.EducationalPerformance;
 using TramsDataApi.UseCases;
 
 namespace TramsDataApi.Controllers
 {
+    /// <summary>
+    /// Manages operations related to Key Stage Educational Performance.
+    /// </summary>
     [ApiController]
     [ApiVersion("1.0")]
+    [SwaggerTag("Key Stage Performance Data Endpoints")]
     public class KeyStagePerformanceController : ControllerBase
     {
         private readonly IGetKeyStagePerformanceByUrn _getKeyStagePerformanceByUrn;
@@ -22,9 +27,20 @@ public KeyStagePerformanceController(
             _getKeyStagePerformanceByUrn = getKeyStagePerformanceByUrn;
             _logger = logger;
         }
-
+
+        /// <summary>
+        /// Retrieves educational performance data for an establishment by its URN.
+        /// </summary>
+        /// <param name="urn">The URN identifier of the establishment.</param>
+        /// <returns>An EducationalPerformanceResponse object or NotFound if unavailable.</returns>
         [HttpGet]
         [Route("educationPerformance/{urn}")]
+        [SwaggerOperation(
+            Summary = "Retrieve Educational Performance by URN",
+            Description = "Returns educational performance data identified by URN."
+        )]
+        [SwaggerResponse(200, "Successfully found and returned the educational performance data.")]
+        [SwaggerResponse(404, "Educational performance data with the specified URN not found.")]
         public ActionResult<EducationalPerformanceResponse> GetEducationPerformanceByUrn(string urn)
         {
             _logger.LogInformation($"Attempting to get Performance Data for URN {urn}");