diff --git a/TramsDataApi/Controllers/EstablishmentsController.cs b/TramsDataApi/Controllers/EstablishmentsController.cs index b0a4c2d0b..12d902370 100644 --- a/TramsDataApi/Controllers/EstablishmentsController.cs +++ b/TramsDataApi/Controllers/EstablishmentsController.cs @@ -41,42 +41,42 @@ public EstablishmentsController( } /// - /// Retrieves an establishment by its UKPRN. + /// Retrieves an establishment by its UK Provider Reference Number (UKPRN). /// - /// The UKPRN of the establishment. + /// The UK Provider Reference Number (UKPRN) of the establishment. /// An establishment or NotFound if not available. [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 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(establishment)); return Ok(establishment); } /// - /// Retrieves a list of establishment URNs by region. + /// Retrieves a list of establishment Unique Reference Numbers (URNs) by region. /// /// Array of regions. - /// List of establishment URNs or NotFound if none are available. + /// List of establishment Unique Reference Numbers (URNs) or NotFound if none are available. [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> 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) @@ -84,32 +84,32 @@ public ActionResult> GetURNsByRegion([FromQuery] string[] regio _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); } /// - /// Retrieves an establishment by its URN. + /// Retrieves an establishment by its Unique Reference Number (URN). /// - /// The URN of the establishment. + /// The Unique Reference Number (URN) of the establishment. /// An establishment or NotFound if not available. [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 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(establishment)); return Ok(establishment); } @@ -132,29 +132,29 @@ public ActionResult> SearchEstablishments([Fr } /// - /// Retrieves a list of establishments by their URNs. + /// Retrieves a list of establishments by their Unique Reference Numbers (URNs). /// - /// Contains URNs of the establishments. + /// Contains Unique Reference Number (URNs) of the establishments. /// List of establishments or NotFound if none are available. [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> 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); } diff --git a/TramsDataApi/Controllers/KeyStagePerformanceController.cs b/TramsDataApi/Controllers/KeyStagePerformanceController.cs index 84d6806f1..7c3d2ced7 100644 --- a/TramsDataApi/Controllers/KeyStagePerformanceController.cs +++ b/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 { + /// + /// Manages operations related to Key Stage Educational Performance. + /// [ApiController] [ApiVersion("1.0")] + [SwaggerTag("Key Stage Performance Data Endpoints")] public class KeyStagePerformanceController : ControllerBase { private readonly IGetKeyStagePerformanceByUrn _getKeyStagePerformanceByUrn; @@ -22,19 +27,30 @@ public KeyStagePerformanceController( _getKeyStagePerformanceByUrn = getKeyStagePerformanceByUrn; _logger = logger; } - + + /// + /// Retrieves educational performance data for an establishment by its Unique Reference Number (URN). + /// + /// The Unique Reference Number (URN) identifier of the establishment. + /// An EducationalPerformanceResponse object or NotFound if unavailable. [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 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(performanceData)); return Ok(performanceData); } diff --git a/TramsDataApi/Controllers/TrustsController.cs b/TramsDataApi/Controllers/TrustsController.cs index 73e9da935..36e0fd859 100644 --- a/TramsDataApi/Controllers/TrustsController.cs +++ b/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 { + /// + /// Handles operations related to Trusts. + /// [ApiController] [ApiVersion("1.0")] + [SwaggerTag("Trust Endpoints")] public class TrustsController : ControllerBase { private readonly IGetTrustByUkprn _getTrustByUkprn; @@ -22,27 +27,46 @@ public TrustsController(IGetTrustByUkprn getTrustByUkprn, ISearchTrusts searchTr _searchTrusts = searchTrusts; _logger = logger; } - + + /// + /// Retrieves a Trust by its UK Provider Reference Number (UKPRN). + /// + /// The UK Provider Reference Number (UKPRN) identifier. + /// A Trust or NotFound if not available. [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 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); } + /// + /// Searches for Trusts based on query parameters. + /// + /// Name of the group. + /// UK Provider Reference Number (UKPRN) identifier. + /// Companies House Number. + /// Pagination page. + /// Number of results per page. + /// A list of Trusts that meet the search criteria. [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> SearchTrusts(string groupName, string ukPrn, string companiesHouseNumber, int page = 1, int count = 10) { _logger.LogInformation( diff --git a/TramsDataApi/Controllers/V2/BaselineTrackerController.cs b/TramsDataApi/Controllers/V2/BaselineTrackerController.cs index 97887f8b8..4c56990a9 100644 --- a/TramsDataApi/Controllers/V2/BaselineTrackerController.cs +++ b/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 { + /// + /// Manages baseline tracker-related operations. + /// [ApiVersion("2.0")] [ApiController] [Route("v{version:apiVersion}/basline-tracker")] + [SwaggerTag("Operations related to Baseline Tracking")] public class BaselineTrackerController : ControllerBase { private readonly ILogger _logger; @@ -28,9 +33,21 @@ public BaselineTrackerController(ILogger logger, _getAllBBaselineTrackerRequestByStatus = getAllBBaselineTrackerRequestByStatus; } - [HttpGet] - [MapToApiVersion("2.0")] - public ActionResult> Get( + /// + /// Retrieves a paginated list of baseline trackers. + /// + /// Comma-separated list of states to filter by. + /// The page number to return. + /// The number of items per page. + /// A paginated ApiResponse containing BaselineTrackerResponse objects. + [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> Get( [FromQuery] string states = null, [FromQuery] int page = 1, [FromQuery] int count = 50) diff --git a/TramsDataApi/Controllers/V2/TrustsController.cs b/TramsDataApi/Controllers/V2/TrustsController.cs index c658fd212..51a51d6d4 100644 --- a/TramsDataApi/Controllers/V2/TrustsController.cs +++ b/TramsDataApi/Controllers/V2/TrustsController.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 { + /// + /// Manages trusts operations. + /// [ApiVersion("2.0")] [ApiController] [Route("v{version:apiVersion}/")] + [SwaggerTag("Operations related to Trusts")] public class TrustsController : ControllerBase { private readonly IGetTrustByUkprn _getTrustByUkPrn; @@ -27,8 +32,16 @@ public TrustsController(IGetTrustByUkprn getTrustByUkPrn, ISearchTrusts searchTr _logger = logger; } + /// + /// Searches for trusts based on given criteria. + /// + /// + /// Search can be performed using the groupName, UK Provider Reference Number (UKPRN), and companiesHouseNumber parameters. + /// [HttpGet("trusts")] [MapToApiVersion("2.0")] + [SwaggerOperation(Summary = "Search Trusts", Description = "Search for trusts using the specified parameters.")] + [SwaggerResponse(200, "Successfully found and returned the list of trusts.")] public ActionResult> SearchTrusts(string groupName, string ukPrn, string companiesHouseNumber, int page = 1, int count = 50, bool includeEstablishments = true) { @@ -54,9 +67,15 @@ public ActionResult> SearchTrusts(string gro return new OkObjectResult(response); } + /// + /// Retrieves a specific trust by UK Provider Reference Number (UKPRN). + /// [HttpGet] [Route("trust/{ukprn}")] [MapToApiVersion("2.0")] + [SwaggerOperation(Summary = "Get Trust By UK Provider Reference Number (UKPRN)", Description = "Retrieve a single trust by its UK Provider Reference Number (UKPRN).")] + [SwaggerResponse(200, "Successfully retrieved the trust.")] + [SwaggerResponse(404, "The trust was not found.")] public ActionResult> GetTrustByUkPrn(string ukprn) { _logger.LogInformation("Attempting to get trust by UKPRN {prn}", ukprn); @@ -75,9 +94,15 @@ public ActionResult> GetTrustByUkPrn(string u return new OkObjectResult(response); } + /// + /// Retrieves multiple trusts by their UK Provider Reference Numbers (UKPRNs). + /// [HttpGet] [Route("trusts/bulk")] [MapToApiVersion("2.0")] + [SwaggerOperation(Summary = "Get Trusts By UK Provider Reference Numbers (UKPRNs)", Description = "Retrieve multiple trusts by their UK Provider Reference Numbers (UKPRNs).")] + [SwaggerResponse(200, "Successfully retrieved the trusts.")] + [SwaggerResponse(404, "The trusts were not found.")] public ActionResult> GetByUkprns([FromQuery] GetTrustsByUkprnsRequest request) { var commaSeparatedRequestUkprns = string.Join(",", request.Ukprns);