Merge pull request #404 from DFE-Digital/trusts-v3-swagger

Trust endpoints annotations

Author: dneed-nimble

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
 {
+    /// <summary>
+    /// Manages operations related to trusts using the Master schema.
+    /// </summary>
     [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;
         }
 
+        /// <summary>
+        /// Searches for trusts based on given criteria.
+        /// </summary>
+        /// <remarks>
+        /// Search can be performed using the groupName, ukPrn, and companiesHouseNumber parameters.
+        /// </remarks>
         [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<ApiResponseV2<TrustSummaryResponse>> SearchTrusts(string groupName, string ukPrn, string companiesHouseNumber, 
             int page = 1, int count = 50, bool includeEstablishments = true)
         {
@@ -50,9 +63,15 @@ public ActionResult<ApiResponseV2<TrustSummaryResponse>> SearchTrusts(string gro
             return new OkObjectResult(response);
         }
 
+        /// <summary>
+        /// Retrieves a specific trust by UKPRN.
+        /// </summary>
         [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<ApiSingleResponseV2<MasterTrustResponse>> GetTrustByUkPrn(string ukprn)
         {
             _logger.LogInformation("Attempting to get trust by UKPRN {prn}", ukprn);