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(