From a885a4b9986e2adc84569e683640d058ee5541d5 Mon Sep 17 00:00:00 2001 From: Dominic NEED Date: Fri, 6 Oct 2023 13:47:10 +0100 Subject: [PATCH 1/5] documentation for trusts --- TramsDataApi/Controllers/TrustsController.cs | 26 +++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/TramsDataApi/Controllers/TrustsController.cs b/TramsDataApi/Controllers/TrustsController.cs index 73e9da935..f3b57a915 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,9 +27,17 @@ public TrustsController(IGetTrustByUkprn getTrustByUkprn, ISearchTrusts searchTr _searchTrusts = searchTrusts; _logger = logger; } - + + /// + /// Retrieves a Trust by its UKPRN. + /// + /// The UKPRN identifier. + /// A Trust or NotFound if not available. [HttpGet] [Route("trust/{ukprn}")] + [SwaggerOperation(Summary = "Retrieve Trust by UKPRN", Description = "Returns a Trust identified by UKPRN.")] + [SwaggerResponse(200, "Successfully found and returned the Trust.")] + [SwaggerResponse(404, "Trust with specified UKPRN not found.")] public ActionResult GetTrustByUkprn(string ukprn) { _logger.LogInformation($"Attempting to get trust by UKPRN {ukprn}"); @@ -41,8 +54,19 @@ public ActionResult GetTrustByUkprn(string ukprn) return Ok(trust); } + /// + /// Searches for Trusts based on query parameters. + /// + /// Name of the group. + /// 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( From 7d2c45a4a1c2664d28e1dad5dd00fbfcc7e2937a Mon Sep 17 00:00:00 2001 From: Dominic NEED Date: Fri, 6 Oct 2023 13:50:25 +0100 Subject: [PATCH 2/5] key stage endpoint documentation --- .../KeyStagePerformanceController.cs | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/TramsDataApi/Controllers/KeyStagePerformanceController.cs b/TramsDataApi/Controllers/KeyStagePerformanceController.cs index 84d6806f1..ba53dd281 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("Operations related to Key Stage Performance Data")] public class KeyStagePerformanceController : ControllerBase { private readonly IGetKeyStagePerformanceByUrn _getKeyStagePerformanceByUrn; @@ -22,9 +27,20 @@ public KeyStagePerformanceController( _getKeyStagePerformanceByUrn = getKeyStagePerformanceByUrn; _logger = logger; } - + + /// + /// Retrieves educational performance data for an establishment by its URN. + /// + /// The URN identifier of the establishment. + /// An EducationalPerformanceResponse object or NotFound if unavailable. [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 GetEducationPerformanceByUrn(string urn) { _logger.LogInformation($"Attempting to get Performance Data for URN {urn}"); From eab77ae91944508a7f565fc352e1751c8ad66f42 Mon Sep 17 00:00:00 2001 From: Dominic NEED Date: Fri, 6 Oct 2023 13:51:20 +0100 Subject: [PATCH 3/5] Swagger tag update --- TramsDataApi/Controllers/KeyStagePerformanceController.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TramsDataApi/Controllers/KeyStagePerformanceController.cs b/TramsDataApi/Controllers/KeyStagePerformanceController.cs index ba53dd281..65e139df8 100644 --- a/TramsDataApi/Controllers/KeyStagePerformanceController.cs +++ b/TramsDataApi/Controllers/KeyStagePerformanceController.cs @@ -14,7 +14,7 @@ namespace TramsDataApi.Controllers /// [ApiController] [ApiVersion("1.0")] - [SwaggerTag("Operations related to Key Stage Performance Data")] + [SwaggerTag("Key Stage Performance Data Endpoints")] public class KeyStagePerformanceController : ControllerBase { private readonly IGetKeyStagePerformanceByUrn _getKeyStagePerformanceByUrn; From c38f46a808a6605bcd3ff5e9355db6592b6dd0e7 Mon Sep 17 00:00:00 2001 From: Dominic NEED Date: Wed, 11 Oct 2023 13:21:54 +0100 Subject: [PATCH 4/5] Added baseline tracker documentation and flattened acronyms --- .../Controllers/EstablishmentsController.cs | 54 +++++++++---------- .../KeyStagePerformanceController.cs | 16 +++--- TramsDataApi/Controllers/TrustsController.cs | 16 +++--- .../V2/BaselineTrackerController.cs | 23 ++++++-- 4 files changed, 63 insertions(+), 46 deletions(-) diff --git a/TramsDataApi/Controllers/EstablishmentsController.cs b/TramsDataApi/Controllers/EstablishmentsController.cs index b0a4c2d0b..aacfa0e2d 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 65e139df8..133d5b1d4 100644 --- a/TramsDataApi/Controllers/KeyStagePerformanceController.cs +++ b/TramsDataApi/Controllers/KeyStagePerformanceController.cs @@ -29,28 +29,28 @@ public KeyStagePerformanceController( } /// - /// Retrieves educational performance data for an establishment by its URN. + /// Retrieves educational performance data for an establishment by its Unique reference number (URN). /// - /// The URN identifier of the establishment. + /// 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 URN", - Description = "Returns educational performance data identified by URN." + 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 URN not found.")] + [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 f3b57a915..36e0fd859 100644 --- a/TramsDataApi/Controllers/TrustsController.cs +++ b/TramsDataApi/Controllers/TrustsController.cs @@ -29,27 +29,27 @@ public TrustsController(IGetTrustByUkprn getTrustByUkprn, ISearchTrusts searchTr } /// - /// Retrieves a Trust by its UKPRN. + /// Retrieves a Trust by its UK Provider Reference Number (UKPRN). /// - /// The UKPRN identifier. + /// The UK Provider Reference Number (UKPRN) identifier. /// A Trust or NotFound if not available. [HttpGet] [Route("trust/{ukprn}")] - [SwaggerOperation(Summary = "Retrieve Trust by UKPRN", Description = "Returns a Trust identified by 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 UKPRN not found.")] + [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); } @@ -58,7 +58,7 @@ public ActionResult GetTrustByUkprn(string ukprn) /// Searches for Trusts based on query parameters. /// /// Name of the group. - /// UKPRN identifier. + /// UK Provider Reference Number (UKPRN) identifier. /// Companies House Number. /// Pagination page. /// Number of results per page. 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) From acc27a7185d9c8a2b7750f42c8bc8af2e551ad2c Mon Sep 17 00:00:00 2001 From: Dominic NEED Date: Thu, 12 Oct 2023 09:36:29 +0100 Subject: [PATCH 5/5] Updated casing --- .../Controllers/EstablishmentsController.cs | 40 +++++++++---------- .../KeyStagePerformanceController.cs | 16 ++++---- .../Controllers/V2/TrustsController.cs | 25 ++++++++++++ 3 files changed, 53 insertions(+), 28 deletions(-) diff --git a/TramsDataApi/Controllers/EstablishmentsController.cs b/TramsDataApi/Controllers/EstablishmentsController.cs index aacfa0e2d..12d902370 100644 --- a/TramsDataApi/Controllers/EstablishmentsController.cs +++ b/TramsDataApi/Controllers/EstablishmentsController.cs @@ -65,18 +65,18 @@ public ActionResult GetByUkprn(string ukprn) return Ok(establishment); } /// - /// Retrieves a list of establishment Unique reference numbers (URNs) by region. + /// Retrieves a list of establishment Unique Reference Numbers (URNs) by region. /// /// Array of regions. - /// List of establishment Unique reference numbers (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 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).")] + [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 Unique reference numbers (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 Unique reference numbers (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 Unique reference number (URN). + /// Retrieves an establishment by its Unique Reference Number (URN). /// - /// The Unique reference number (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 Unique reference number (URN)", Description = "Returns an establishment specified by Unique reference number (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 Unique reference number (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 Unique reference number (URN) {urn}"); + _logger.LogInformation($"Attempting to get Establishment by Unique Reference Number (URN) {urn}"); if (establishment == null) { - _logger.LogInformation($"No Establishment found for Unique reference number (URN) {urn}"); + _logger.LogInformation($"No Establishment found for Unique Reference Number (URN) {urn}"); return NotFound(); } - _logger.LogInformation($"Returning Establishment with Unique reference number (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 Unique reference numbers (URNs). + /// Retrieves a list of establishments by their Unique Reference Numbers (URNs). /// - /// Contains Unique reference number (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 Unique reference number (URNs)", Description = "Returns a list of establishments specified by Unique reference numbers (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 Unique reference numbers (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 Unique reference numbers (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 Unique reference numbers (URNs): {commaSeparatedRequestUrns}"); + _logger.LogInformation($"No establishment was found any of the requested Unique Reference Numbers (URNs): {commaSeparatedRequestUrns}"); return NotFound(); } - _logger.LogInformation($"Returning Establishments for Unique reference numbers (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 133d5b1d4..7c3d2ced7 100644 --- a/TramsDataApi/Controllers/KeyStagePerformanceController.cs +++ b/TramsDataApi/Controllers/KeyStagePerformanceController.cs @@ -29,28 +29,28 @@ public KeyStagePerformanceController( } /// - /// Retrieves educational performance data for an establishment by its Unique reference number (URN). + /// Retrieves educational performance data for an establishment by its Unique Reference Number (URN). /// - /// The Unique reference number (URN) identifier of the establishment. + /// 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)." + 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.")] + [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 Unique reference number (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 Unique reference number (URN) {urn}"); + _logger.LogInformation($"No Performance Data found for Unique Reference Number (URN) {urn}"); return NotFound(); } - _logger.LogInformation($"Returning Performance Data for Unique reference number (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/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);