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);