Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

V1 keystage documentation #393

Merged
merged 4 commits into from
Oct 11, 2023
Merged

V1 keystage documentation #393

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ba12030
V1 establishment endpoints documentation
Oct 6, 2023
a885a4b
documentation for trusts
Oct 6, 2023
7d2c45a
key stage endpoint documentation
Oct 6, 2023
eab77ae
Swagger tag update
Oct 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions TramsDataApi/Controllers/EstablishmentsController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
/// <summary>
/// Manages establishment-related operations.
/// </summary>
[ApiController]
[ApiVersion("1.0")]
[SwaggerTag("Establishment Endpoints")]
public class EstablishmentsController : ControllerBase
{
private readonly IGetEstablishmentByUkprn _getEstablishmentByUkprn;
Expand All @@ -35,8 +40,16 @@ public EstablishmentsController(
_logger = logger;
}

/// <summary>
/// Retrieves an establishment by its UKPRN.
/// </summary>
/// <param name="ukprn">The UKPRN of the establishment.</param>
/// <returns>An establishment or NotFound if not available.</returns>
[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<EstablishmentResponse> GetByUkprn(string ukprn)
{
_logger.LogInformation($"Attempting to get Establishment by UKPRN {ukprn}");
Expand All @@ -51,8 +64,16 @@ public ActionResult<EstablishmentResponse> GetByUkprn(string ukprn)
_logger.LogDebug(JsonSerializer.Serialize<EstablishmentResponse>(establishment));
return Ok(establishment);
}
/// <summary>
/// Retrieves a list of establishment URNs by region.
/// </summary>
/// <param name="regions">Array of regions.</param>
/// <returns>List of establishment URNs or NotFound if none are available.</returns>
[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<IEnumerable<int>> GetURNsByRegion([FromQuery] string[] regions)
{
_logger.LogInformation($"Attempting to get Establishment URNs by Region {regions}");
Expand All @@ -68,8 +89,16 @@ public ActionResult<IEnumerable<int>> GetURNsByRegion([FromQuery] string[] regio
return Ok(establishment);
}

/// <summary>
/// Retrieves an establishment by its URN.
/// </summary>
/// <param name="urn">The URN of the establishment.</param>
/// <returns>An establishment or NotFound if not available.</returns>
[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<EstablishmentResponse> GetByUrn(int urn)
{
var establishment = _getEstablishmentByUrn.Execute(new GetEstablishmentByUrnRequest { URN = urn });
Expand All @@ -85,8 +114,15 @@ public ActionResult<EstablishmentResponse> GetByUrn(int urn)
return Ok(establishment);
}

/// <summary>
/// Searches for establishments based on a query.
/// </summary>
/// <param name="request">Search criteria.</param>
/// <returns>List of establishments that meet the search criteria.</returns>
[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<List<EstablishmentSummaryResponse>> SearchEstablishments([FromQuery] SearchEstablishmentsRequest request)
{
_logger.LogInformation($"Searching for Establishments");
Expand All @@ -95,8 +131,16 @@ public ActionResult<List<EstablishmentSummaryResponse>> SearchEstablishments([Fr
return Ok(establishments);
}

/// <summary>
/// Retrieves a list of establishments by their URNs.
/// </summary>
/// <param name="request">Contains URNs of the establishments.</param>
/// <returns>List of establishments or NotFound if none are available.</returns>
[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<List<EstablishmentResponse>> GetByUrns([FromQuery] GetEstablishmentsByUrnsRequest request)
{
var commaSeparatedRequestUrns = string.Join(",", request.Urns);
Expand Down
18 changes: 17 additions & 1 deletion TramsDataApi/Controllers/KeyStagePerformanceController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,19 @@
using System.Text.Json;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Swashbuckle.AspNetCore.Annotations;
using TramsDataApi.DatabaseModels;
using TramsDataApi.ResponseModels.EducationalPerformance;
using TramsDataApi.UseCases;

namespace TramsDataApi.Controllers
{
/// <summary>
/// Manages operations related to Key Stage Educational Performance.
/// </summary>
[ApiController]
[ApiVersion("1.0")]
[SwaggerTag("Key Stage Performance Data Endpoints")]
public class KeyStagePerformanceController : ControllerBase
{
private readonly IGetKeyStagePerformanceByUrn _getKeyStagePerformanceByUrn;
Expand All @@ -22,9 +27,20 @@ public KeyStagePerformanceController(
_getKeyStagePerformanceByUrn = getKeyStagePerformanceByUrn;
_logger = logger;
}


/// <summary>
/// Retrieves educational performance data for an establishment by its URN.
/// </summary>
/// <param name="urn">The URN identifier of the establishment.</param>
/// <returns>An EducationalPerformanceResponse object or NotFound if unavailable.</returns>
[HttpGet]
[Route("educationPerformance/{urn}")]
[SwaggerOperation(
Summary = "Retrieve Educational Performance by URN",
Description = "Returns educational performance data identified by URN."
)]
[SwaggerResponse(200, "Successfully found and returned the educational performance data.")]
[SwaggerResponse(404, "Educational performance data with the specified URN not found.")]
public ActionResult<EducationalPerformanceResponse> GetEducationPerformanceByUrn(string urn)
{
_logger.LogInformation($"Attempting to get Performance Data for URN {urn}");
Expand Down
26 changes: 25 additions & 1 deletion TramsDataApi/Controllers/TrustsController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
/// <summary>
/// Handles operations related to Trusts.
/// </summary>
[ApiController]
[ApiVersion("1.0")]
[SwaggerTag("Trust Endpoints")]
public class TrustsController : ControllerBase
{
private readonly IGetTrustByUkprn _getTrustByUkprn;
Expand All @@ -22,9 +27,17 @@ public TrustsController(IGetTrustByUkprn getTrustByUkprn, ISearchTrusts searchTr
_searchTrusts = searchTrusts;
_logger = logger;
}


/// <summary>
/// Retrieves a Trust by its UKPRN.
/// </summary>
/// <param name="ukprn">The UKPRN identifier.</param>
/// <returns>A Trust or NotFound if not available.</returns>
[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<TrustResponse> GetTrustByUkprn(string ukprn)
{
_logger.LogInformation($"Attempting to get trust by UKPRN {ukprn}");
Expand All @@ -41,8 +54,19 @@ public ActionResult<TrustResponse> GetTrustByUkprn(string ukprn)
return Ok(trust);
}

/// <summary>
/// Searches for Trusts based on query parameters.
/// </summary>
/// <param name="groupName">Name of the group.</param>
/// <param name="ukPrn">UKPRN identifier.</param>
/// <param name="companiesHouseNumber">Companies House Number.</param>
/// <param name="page">Pagination page.</param>
/// <param name="count">Number of results per page.</param>
/// <returns>A list of Trusts that meet the search criteria.</returns>
[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<List<TrustSummaryResponse>> SearchTrusts(string groupName, string ukPrn, string companiesHouseNumber, int page = 1, int count = 10)
{
_logger.LogInformation(
Expand Down
Loading