diff --git a/TramsDataApi/Controllers/V3/TrustsController.cs b/TramsDataApi/Controllers/V3/TrustsController.cs index 792e0ed07..234fd579b 100644 --- a/TramsDataApi/Controllers/V3/TrustsController.cs +++ b/TramsDataApi/Controllers/V3/TrustsController.cs @@ -2,14 +2,19 @@ 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.V3 { + /// + /// Manages operations related to trusts using the Master schema. + /// [ApiVersion("3.0")] [ApiController] [Route("v{version:apiVersion}/")] + [SwaggerTag("Operations related to Trusts using the Master schema")] public class TrustsController : ControllerBase { private readonly IGetMstrTrustByUkprn _getMstrTrustByUkPrn; @@ -23,8 +28,16 @@ public TrustsController(IGetMstrTrustByUkprn getMstrTrustByUkPrn, IMstrSearchTru _logger = logger; } + /// + /// Searches for trusts based on given criteria. + /// + /// + /// Search can be performed using the groupName, ukPrn, and companiesHouseNumber parameters. + /// [HttpGet("trusts")] [MapToApiVersion("3.0")] + [SwaggerOperation(Summary = "Search Trusts", Description = "Search for trusts using the specified parameters, within the Master schema.")] + [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) { @@ -50,9 +63,15 @@ public ActionResult> SearchTrusts(string gro return new OkObjectResult(response); } + /// + /// Retrieves a specific trust by UKPRN. + /// [HttpGet] [Route("trust/{ukprn}")] [MapToApiVersion("3.0")] + [SwaggerOperation(Summary = "Get Trust By UKPRN", Description = "Retrieve a single trust by its 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);