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