From ba120302fc0a3f68c856224d0fd72a017f0d4d96 Mon Sep 17 00:00:00 2001 From: Dominic NEED Date: Fri, 6 Oct 2023 13:42:19 +0100 Subject: [PATCH 1/4] V1 establishment endpoints documentation --- .../Controllers/EstablishmentsController.cs | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/TramsDataApi/Controllers/EstablishmentsController.cs b/TramsDataApi/Controllers/EstablishmentsController.cs index 887c4c159..b0a4c2d0b 100644 --- a/TramsDataApi/Controllers/EstablishmentsController.cs +++ b/TramsDataApi/Controllers/EstablishmentsController.cs @@ -2,14 +2,19 @@ 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 { + /// + /// Manages establishment-related operations. + /// [ApiController] [ApiVersion("1.0")] + [SwaggerTag("Establishment Endpoints")] public class EstablishmentsController : ControllerBase { private readonly IGetEstablishmentByUkprn _getEstablishmentByUkprn; @@ -35,8 +40,16 @@ public EstablishmentsController( _logger = logger; } + /// + /// Retrieves an establishment by its UKPRN. + /// + /// The 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.")] + [SwaggerResponse(200, "Successfully found and returned the establishment.")] + [SwaggerResponse(404, "Establishment with specified UKPRN not found.")] public ActionResult GetByUkprn(string ukprn) { _logger.LogInformation($"Attempting to get Establishment by UKPRN {ukprn}"); @@ -51,8 +64,16 @@ public ActionResult GetByUkprn(string ukprn) _logger.LogDebug(JsonSerializer.Serialize(establishment)); return Ok(establishment); } + /// + /// Retrieves a list of establishment URNs by region. + /// + /// Array of regions. + /// List of establishment 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.")] + [SwaggerResponse(404, "No establishments found for specified regions.")] public ActionResult> GetURNsByRegion([FromQuery] string[] regions) { _logger.LogInformation($"Attempting to get Establishment URNs by Region {regions}"); @@ -68,8 +89,16 @@ public ActionResult> GetURNsByRegion([FromQuery] string[] regio return Ok(establishment); } + /// + /// Retrieves an establishment by its URN. + /// + /// The 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.")] + [SwaggerResponse(200, "Successfully found and returned the establishment.")] + [SwaggerResponse(404, "Establishment with specified URN not found.")] public ActionResult GetByUrn(int urn) { var establishment = _getEstablishmentByUrn.Execute(new GetEstablishmentByUrnRequest { URN = urn }); @@ -85,8 +114,15 @@ public ActionResult GetByUrn(int urn) return Ok(establishment); } + /// + /// Searches for establishments based on a query. + /// + /// Search criteria. + /// List of establishments that meet the search criteria. [HttpGet] [Route("establishments")] + [SwaggerOperation(Summary = "Search for Establishments", Description = "Returns a list of establishments based on search criteria.")] + [SwaggerResponse(200, "Successfully executed the search and returned establishments.")] public ActionResult> SearchEstablishments([FromQuery] SearchEstablishmentsRequest request) { _logger.LogInformation($"Searching for Establishments"); @@ -95,8 +131,16 @@ public ActionResult> SearchEstablishments([Fr return Ok(establishments); } + /// + /// Retrieves a list of establishments by their URNs. + /// + /// Contains 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.")] + [SwaggerResponse(200, "Successfully found and returned the establishments.")] + [SwaggerResponse(404, "Establishments with specified URNs not found.")] public ActionResult> GetByUrns([FromQuery] GetEstablishmentsByUrnsRequest request) { var commaSeparatedRequestUrns = string.Join(",", request.Urns); From a885a4b9986e2adc84569e683640d058ee5541d5 Mon Sep 17 00:00:00 2001 From: Dominic NEED Date: Fri, 6 Oct 2023 13:47:10 +0100 Subject: [PATCH 2/4] 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 3/4] 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 4/4] 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;