V2 baseline documentation

TramsDataApi/Controllers/EstablishmentsController.cs

@@ -41,75 +41,75 @@ public EstablishmentsController(
         }
 
         /// <summary>
-        /// Retrieves an establishment by its UKPRN.
+        /// Retrieves an establishment by its UK Provider Reference Number (UKPRN).
         /// </summary>
-        /// <param name="ukprn">The UKPRN of the establishment.</param>
+        /// <param name="ukprn">The UK Provider Reference Number (UKPRN) of the establishment.</param>
         /// <returns>An establishment or NotFound if not available.</returns>
         [HttpGet]
         [Route("establishment/{ukprn}")]
-        [SwaggerOperation(Summary = "Get Establishment by UKPRN", Description = "Returns an establishment specified by UKPRN.")]
+        [SwaggerOperation(Summary = "Get Establishment by UK Provider Reference Number (UKPRN)", Description = "Returns an establishment specified by UK Provider Reference Number (UKPRN).")]
         [SwaggerResponse(200, "Successfully found and returned the establishment.")]
-        [SwaggerResponse(404, "Establishment with specified UKPRN not found.")]
+        [SwaggerResponse(404, "Establishment with specified UK Provider Reference Number (UKPRN) not found.")]
         public ActionResult<EstablishmentResponse> GetByUkprn(string ukprn)
         {
-            _logger.LogInformation($"Attempting to get Establishment by UKPRN {ukprn}");
+            _logger.LogInformation($"Attempting to get Establishment by UK Provider Reference Number (UKPRN) {ukprn}");
             var establishment = _getEstablishmentByUkprn.Execute(ukprn);
 
             if (establishment == null)
             {
-                _logger.LogInformation($"No Establishment found for UKPRN {ukprn}");
+                _logger.LogInformation($"No Establishment found for UK Provider Reference Number (UKPRN) {ukprn}");
                 return NotFound();
             }
-            _logger.LogInformation($"Returning Establishment with UKPRN {ukprn}");
+            _logger.LogInformation($"Returning Establishment with UK Provider Reference Number (UKPRN) {ukprn}");
             _logger.LogDebug(JsonSerializer.Serialize<EstablishmentResponse>(establishment));
             return Ok(establishment);
         }
         /// <summary>
-        /// Retrieves a list of establishment URNs by region.
+        /// Retrieves a list of establishment Unique reference numbers (URNs) by region.
         /// </summary>
         /// <param name="regions">Array of regions.</param>
-        /// <returns>List of establishment URNs or NotFound if none are available.</returns>
+        /// <returns>List of establishment Unique reference numbers (URNs) or NotFound if none are available.</returns>
         [HttpGet]
         [Route("establishment/regions")]
-        [SwaggerOperation(Summary = "Get Establishment URNs by Region", Description = "Returns a list of establishment URNs by specified regions.")]
-        [SwaggerResponse(200, "Successfully found and returned the establishment URNs.")]
+        [SwaggerOperation(Summary = "Get Establishment Unique reference numbers (URNs) by Region", Description = "Returns a list of establishment Unique reference numbers (URNs) by specified regions.")]
+        [SwaggerResponse(200, "Successfully found and returned the establishment Unique reference numbers (URNs).")]
         [SwaggerResponse(404, "No establishments found for specified regions.")]
         public ActionResult<IEnumerable<int>> GetURNsByRegion([FromQuery] string[] regions)
         {
-            _logger.LogInformation($"Attempting to get Establishment URNs by Region {regions}");
+            _logger.LogInformation($"Attempting to get Establishment Unique reference numbers (URNs) by Region {regions}");
             var establishment = _getEstablishmentURNsByRegion.Execute(regions);
 
             if (establishment == null)
             {
                 _logger.LogInformation($"No Establishments found for Region {regions}");
                 return NotFound();
             }
-            _logger.LogInformation($"Returning Establishment URNs with Region {regions}");
+            _logger.LogInformation($"Returning Establishment Unique reference numbers (URNs) with Region {regions}");
             _logger.LogDebug(JsonSerializer.Serialize(establishment));
             return Ok(establishment);
         }
 
         /// <summary>
-        /// Retrieves an establishment by its URN.
+        /// Retrieves an establishment by its Unique reference number (URN).
         /// </summary>
-        /// <param name="urn">The URN of the establishment.</param>
+        /// <param name="urn">The Unique reference number (URN) of the establishment.</param>
         /// <returns>An establishment or NotFound if not available.</returns>
         [HttpGet]
         [Route("establishment/urn/{urn}")]
-        [SwaggerOperation(Summary = "Get Establishment by URN", Description = "Returns an establishment specified by URN.")]
+        [SwaggerOperation(Summary = "Get Establishment by Unique reference number (URN)", Description = "Returns an establishment specified by Unique reference number (URN).")]
         [SwaggerResponse(200, "Successfully found and returned the establishment.")]
-        [SwaggerResponse(404, "Establishment with specified URN not found.")]
+        [SwaggerResponse(404, "Establishment with specified Unique reference number (URN) not found.")]
         public ActionResult<EstablishmentResponse> GetByUrn(int urn)
         {
             var establishment = _getEstablishmentByUrn.Execute(new GetEstablishmentByUrnRequest { URN = urn });
-            _logger.LogInformation($"Attempting to get Establishment by URN {urn}");
+            _logger.LogInformation($"Attempting to get Establishment by Unique reference number (URN) {urn}");
 
             if (establishment == null)
             {
-                _logger.LogInformation($"No Establishment found for URN {urn}");
+                _logger.LogInformation($"No Establishment found for Unique reference number (URN) {urn}");
                 return NotFound();
             }
-            _logger.LogInformation($"Returning Establishment with URN {urn}");
+            _logger.LogInformation($"Returning Establishment with Unique reference number (URN) {urn}");
             _logger.LogDebug(JsonSerializer.Serialize<EstablishmentResponse>(establishment));
             return Ok(establishment);
         }
@@ -132,29 +132,29 @@ public ActionResult<List<EstablishmentSummaryResponse>> SearchEstablishments([Fr
         }
 
         /// <summary>
-        /// Retrieves a list of establishments by their URNs.
+        /// Retrieves a list of establishments by their Unique reference numbers (URNs).
         /// </summary>
-        /// <param name="request">Contains URNs of the establishments.</param>
+        /// <param name="request">Contains Unique reference number (URNs) of the establishments.</param>
         /// <returns>List of establishments or NotFound if none are available.</returns>
         [HttpGet]
         [Route("establishments/bulk")]
-        [SwaggerOperation(Summary = "Get Establishments by URNs", Description = "Returns a list of establishments specified by URNs.")]
+        [SwaggerOperation(Summary = "Get Establishments by Unique reference number (URNs)", Description = "Returns a list of establishments specified by Unique reference numbers (URNs).")]
         [SwaggerResponse(200, "Successfully found and returned the establishments.")]
-        [SwaggerResponse(404, "Establishments with specified URNs not found.")]
+        [SwaggerResponse(404, "Establishments with specified Unique reference numbers (URNs) not found.")]
         public ActionResult<List<EstablishmentResponse>> GetByUrns([FromQuery] GetEstablishmentsByUrnsRequest request)
         {
             var commaSeparatedRequestUrns = string.Join(",", request.Urns);
-            _logger.LogInformation($"Attemping to get establishments by URNs: {commaSeparatedRequestUrns}");
+            _logger.LogInformation($"Attemping to get establishments by Unique reference numbers (URNs): {commaSeparatedRequestUrns}");
 
             var establishments = _getEstablishments.Execute(request);
 
             if (establishments == null)
             {
-                _logger.LogInformation($"No establishment was found any of the requested URNs: {commaSeparatedRequestUrns}");
+                _logger.LogInformation($"No establishment was found any of the requested Unique reference numbers (URNs): {commaSeparatedRequestUrns}");
                 return NotFound();
             }
 
-            _logger.LogInformation($"Returning Establishments for URNs: {commaSeparatedRequestUrns}");
+            _logger.LogInformation($"Returning Establishments for Unique reference numbers (URNs): {commaSeparatedRequestUrns}");
             _logger.LogDebug(JsonSerializer.Serialize(establishments));
             return Ok(establishments);
         }

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,19 +27,30 @@
             _getKeyStagePerformanceByUrn = getKeyStagePerformanceByUrn;
             _logger = logger;
         }
-
+
+        /// <summary>
+        /// Retrieves educational performance data for an establishment by its Unique reference number (URN).
+        /// </summary>
+        /// <param name="urn">The Unique reference number (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 Unique reference number (URN)",
+            Description = "Returns educational performance data identified by Unique reference number (URN)."
+        )]
+        [SwaggerResponse(200, "Successfully found and returned the educational performance data.")]
+        [SwaggerResponse(404, "Educational performance data with the specified Unique reference number (URN) not found.")]
         public ActionResult<EducationalPerformanceResponse> GetEducationPerformanceByUrn(string urn)
         {
-            _logger.LogInformation($"Attempting to get Performance Data for URN {urn}");
+            _logger.LogInformation($"Attempting to get Performance Data for Unique reference number (URN) {urn}");
             var performanceData = _getKeyStagePerformanceByUrn.Execute(urn);
             if (performanceData == null)
             {
-                _logger.LogInformation($"No Performance Data found for URN {urn}");
+                _logger.LogInformation($"No Performance Data found for Unique reference number (URN) {urn}");
                 return NotFound();
             }
-            _logger.LogInformation($"Returning Performance Data for URN {urn}");
+            _logger.LogInformation($"Returning Performance Data for Unique reference number (URN) {urn}");
             _logger.LogDebug(JsonSerializer.Serialize<EducationalPerformanceResponse>(performanceData));
             return Ok(performanceData);
         }

TramsDataApi/Controllers/TrustsController.cs

@@ -3,13 +3,18 @@
 using System.Text.Json;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
+using Swashbuckle.AspNetCore.Annotations;
 using TramsDataApi.ResponseModels;
 using TramsDataApi.UseCases;
 
 namespace TramsDataApi.Controllers
 {
+    /// <summary>
+    /// Handles operations related to Trusts.
+    /// </summary>
     [ApiController]
     [ApiVersion("1.0")]
+    [SwaggerTag("Trust Endpoints")]
     public class TrustsController : ControllerBase
     {
         private readonly IGetTrustByUkprn _getTrustByUkprn;
@@ -22,27 +27,46 @@
             _searchTrusts = searchTrusts;
             _logger = logger;
         }
-
+
+        /// <summary>
+        /// Retrieves a Trust by its UK Provider Reference Number (UKPRN).
+        /// </summary>
+        /// <param name="ukprn">The UK Provider Reference Number (UKPRN) identifier.</param>
+        /// <returns>A Trust or NotFound if not available.</returns>
         [HttpGet]
         [Route("trust/{ukprn}")]
+        [SwaggerOperation(Summary = "Retrieve Trust by UK Provider Reference Number (UKPRN)", Description = "Returns a Trust identified by UK Provider Reference Number (UKPRN).")]
+        [SwaggerResponse(200, "Successfully found and returned the Trust.")]
+        [SwaggerResponse(404, "Trust with specified UK Provider Reference Number (UKPRN) not found.")]
         public ActionResult<TrustResponse> GetTrustByUkprn(string ukprn)
         {
-            _logger.LogInformation($"Attempting to get trust by UKPRN {ukprn}");
+            _logger.LogInformation($"Attempting to get trust by UK Provider Reference Number (UKPRN) {ukprn}");
             var trust = _getTrustByUkprn.Execute(ukprn);
 
             if (trust == null)
             {
-                _logger.LogInformation($"No trust found for UKPRN {ukprn}");
+                _logger.LogInformation($"No trust found for UK Provider Reference Number (UKPRN) {ukprn}");
                 return NotFound();
             }
 
-            _logger.LogInformation($"Returning trust found by UKPRN {ukprn}");
+            _logger.LogInformation($"Returning trust found by UK Provider Reference Number (UKPRN) {ukprn}");
             _logger.LogDebug(JsonSerializer.Serialize(trust));
             return Ok(trust);
         }
 
+        /// <summary>
+        /// Searches for Trusts based on query parameters.
+        /// </summary>
+        /// <param name="groupName">Name of the group.</param>
+        /// <param name="ukPrn">UK Provider Reference Number (UKPRN) identifier.</param>
+        /// <param name="companiesHouseNumber">Companies House Number.</param>
+        /// <param name="page">Pagination page.</param>
+        /// <param name="count">Number of results per page.</param>
+        /// <returns>A list of Trusts that meet the search criteria.</returns>
         [HttpGet]
         [Route("trusts")]
+        [SwaggerOperation(Summary = "Search Trusts", Description = "Returns a list of Trusts based on search criteria.")]
+        [SwaggerResponse(200, "Successfully executed the search and returned Trusts.")]
         public ActionResult<List<TrustSummaryResponse>> SearchTrusts(string groupName, string ukPrn, string companiesHouseNumber, int page = 1, int count = 10)
         {
             _logger.LogInformation(

TramsDataApi/Controllers/V2/BaselineTrackerController.cs

@@ -3,15 +3,20 @@
 using System.Text.Json;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
+using Swashbuckle.AspNetCore.Annotations;
 using TramsDataApi.RequestModels;
 using TramsDataApi.ResponseModels;
 using TramsDataApi.UseCases;
 
 namespace TramsDataApi.Controllers.V2
 {
+    /// <summary>
+    /// Manages baseline tracker-related operations.
+    /// </summary>
     [ApiVersion("2.0")]
     [ApiController]
     [Route("v{version:apiVersion}/basline-tracker")]
+    [SwaggerTag("Operations related to Baseline Tracking")]   
     public class BaselineTrackerController : ControllerBase
     {
         private readonly ILogger<BaselineTrackerController> _logger;
@@ -28,9 +33,21 @@ public BaselineTrackerController(ILogger<BaselineTrackerController> logger,
             _getAllBBaselineTrackerRequestByStatus = getAllBBaselineTrackerRequestByStatus;
         }
 
-		[HttpGet]
-		[MapToApiVersion("2.0")]
-		public ActionResult<ApiResponseV2<BaselineTrackerResponse>> Get(
+        /// <summary>
+        /// Retrieves a paginated list of baseline trackers.
+        /// </summary>
+        /// <param name="states">Comma-separated list of states to filter by.</param>
+        /// <param name="page">The page number to return.</param>
+        /// <param name="count">The number of items per page.</param>
+        /// <returns>A paginated ApiResponse containing BaselineTrackerResponse objects.</returns>
+        [HttpGet]
+        [MapToApiVersion("2.0")]
+        [SwaggerOperation(
+            Summary = "Retrieve Baseline Trackers",
+            Description = "Returns a paginated list of baseline trackers, optionally filtered by states."
+        )]
+        [SwaggerResponse(200, "Successfully found and returned the list of baseline trackers.")]
+        public ActionResult<ApiResponseV2<BaselineTrackerResponse>> Get(
             [FromQuery] string states = null,
             [FromQuery] int page = 1, 
             [FromQuery] int count = 50)