Skip to content

Commit

Permalink
Merge pull request #394 from DFE-Digital/v2-baseline-documentation
Browse files Browse the repository at this point in the history 
V2 baseline documentation
  • Loading branch information
@dneed-nimble
dneed-nimble authored Oct 12, 2023
2 parents cd8e035 + acc27a7 commit aef9ff3
Show file tree
Hide file tree
Showing 5 changed files with 88 additions and 46 deletions.
54 changes: 27 additions & 27 deletions TramsDataApi/Controllers/EstablishmentsController.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,75 +41,75 @@ public EstablishmentsController(
}

/// <summary>
/// Retrieves an establishment by its UKPRN.
/// Retrieves an establishment by its UK Provider Reference Number (UKPRN).
/// </summary>
/// <param name="ukprn">The UKPRN of the establishment.</param>
/// <param name="ukprn">The UK Provider Reference Number (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.")]
[SwaggerOperation(Summary = "Get Establishment by UK Provider Reference Number (UKPRN)", Description = "Returns an establishment specified by UK Provider Reference Number (UKPRN).")]
[SwaggerResponse(200, "Successfully found and returned the establishment.")]
[SwaggerResponse(404, "Establishment with specified UKPRN not found.")]
[SwaggerResponse(404, "Establishment with specified UK Provider Reference Number (UKPRN) not found.")]
public ActionResult<EstablishmentResponse> GetByUkprn(string ukprn)
{
_logger.LogInformation($"Attempting to get Establishment by UKPRN {ukprn}");
_logger.LogInformation($"Attempting to get Establishment by UK Provider Reference Number (UKPRN) {ukprn}");
var establishment = _getEstablishmentByUkprn.Execute(ukprn);

if (establishment == null)
{
_logger.LogInformation($"No Establishment found for UKPRN {ukprn}");
_logger.LogInformation($"No Establishment found for UK Provider Reference Number (UKPRN) {ukprn}");
return NotFound();
}
_logger.LogInformation($"Returning Establishment with UKPRN {ukprn}");
_logger.LogInformation($"Returning Establishment with UK Provider Reference Number (UKPRN) {ukprn}");
_logger.LogDebug(JsonSerializer.Serialize<EstablishmentResponse>(establishment));
return Ok(establishment);
}
/// <summary>
/// Retrieves a list of establishment URNs by region.
/// Retrieves a list of establishment Unique Reference Numbers (URNs) by region.
/// </summary>
/// <param name="regions">Array of regions.</param>
/// <returns>List of establishment URNs or NotFound if none are available.</returns>
/// <returns>List of establishment Unique Reference Numbers (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.")]
[SwaggerOperation(Summary = "Get Establishment Unique Reference Numbers (URNs) by Region", Description = "Returns a list of establishment Unique Reference Numbers (URNs) by specified regions.")]
[SwaggerResponse(200, "Successfully found and returned the establishment Unique Reference Numbers (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}");
_logger.LogInformation($"Attempting to get Establishment Unique Reference Numbers (URNs) by Region {regions}");
var establishment = _getEstablishmentURNsByRegion.Execute(regions);

if (establishment == null)
{
_logger.LogInformation($"No Establishments found for Region {regions}");
return NotFound();
}
_logger.LogInformation($"Returning Establishment URNs with Region {regions}");
_logger.LogInformation($"Returning Establishment Unique Reference Numbers (URNs) with Region {regions}");
_logger.LogDebug(JsonSerializer.Serialize(establishment));
return Ok(establishment);
}

/// <summary>
/// Retrieves an establishment by its URN.
/// Retrieves an establishment by its Unique Reference Number (URN).
/// </summary>
/// <param name="urn">The URN of the establishment.</param>
/// <param name="urn">The Unique Reference Number (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.")]
[SwaggerOperation(Summary = "Get Establishment by Unique Reference Number (URN)", Description = "Returns an establishment specified by Unique Reference Number (URN).")]
[SwaggerResponse(200, "Successfully found and returned the establishment.")]
[SwaggerResponse(404, "Establishment with specified URN not found.")]
[SwaggerResponse(404, "Establishment with specified Unique Reference Number (URN) not found.")]
public ActionResult<EstablishmentResponse> GetByUrn(int urn)
{
var establishment = _getEstablishmentByUrn.Execute(new GetEstablishmentByUrnRequest { URN = urn });
_logger.LogInformation($"Attempting to get Establishment by URN {urn}");
_logger.LogInformation($"Attempting to get Establishment by Unique Reference Number (URN) {urn}");

if (establishment == null)
{
_logger.LogInformation($"No Establishment found for URN {urn}");
_logger.LogInformation($"No Establishment found for Unique Reference Number (URN) {urn}");
return NotFound();
}
_logger.LogInformation($"Returning Establishment with URN {urn}");
_logger.LogInformation($"Returning Establishment with Unique Reference Number (URN) {urn}");
_logger.LogDebug(JsonSerializer.Serialize<EstablishmentResponse>(establishment));
return Ok(establishment);
}
Expand All @@ -132,29 +132,29 @@ public ActionResult<List<EstablishmentSummaryResponse>> SearchEstablishments([Fr
}

/// <summary>
/// Retrieves a list of establishments by their URNs.
/// Retrieves a list of establishments by their Unique Reference Numbers (URNs).
/// </summary>
/// <param name="request">Contains URNs of the establishments.</param>
/// <param name="request">Contains Unique Reference Number (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.")]
[SwaggerOperation(Summary = "Get Establishments by Unique Reference Number (URNs)", Description = "Returns a list of establishments specified by Unique Reference Numbers (URNs).")]
[SwaggerResponse(200, "Successfully found and returned the establishments.")]
[SwaggerResponse(404, "Establishments with specified URNs not found.")]
[SwaggerResponse(404, "Establishments with specified Unique Reference Numbers (URNs) not found.")]
public ActionResult<List<EstablishmentResponse>> GetByUrns([FromQuery] GetEstablishmentsByUrnsRequest request)
{
var commaSeparatedRequestUrns = string.Join(",", request.Urns);
_logger.LogInformation($"Attemping to get establishments by URNs: {commaSeparatedRequestUrns}");
_logger.LogInformation($"Attemping to get establishments by Unique Reference Numbers (URNs): {commaSeparatedRequestUrns}");

var establishments = _getEstablishments.Execute(request);

if (establishments == null)
{
_logger.LogInformation($"No establishment was found any of the requested URNs: {commaSeparatedRequestUrns}");
_logger.LogInformation($"No establishment was found any of the requested Unique Reference Numbers (URNs): {commaSeparatedRequestUrns}");
return NotFound();
}

_logger.LogInformation($"Returning Establishments for URNs: {commaSeparatedRequestUrns}");
_logger.LogInformation($"Returning Establishments for Unique Reference Numbers (URNs): {commaSeparatedRequestUrns}");
_logger.LogDebug(JsonSerializer.Serialize(establishments));
return Ok(establishments);
}
Expand Down
16 changes: 8 additions & 8 deletions TramsDataApi/Controllers/KeyStagePerformanceController.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,28 +29,28 @@ public KeyStagePerformanceController(
}

/// <summary>
/// Retrieves educational performance data for an establishment by its URN.
/// Retrieves educational performance data for an establishment by its Unique Reference Number (URN).
/// </summary>
/// <param name="urn">The URN identifier of the establishment.</param>
/// <param name="urn">The Unique Reference Number (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."
Summary = "Retrieve Educational Performance by Unique Reference Number (URN)",
Description = "Returns educational performance data identified by Unique Reference Number (URN)."
)]
[SwaggerResponse(200, "Successfully found and returned the educational performance data.")]
[SwaggerResponse(404, "Educational performance data with the specified URN not found.")]
[SwaggerResponse(404, "Educational performance data with the specified Unique Reference Number (URN) not found.")]
public ActionResult<EducationalPerformanceResponse> GetEducationPerformanceByUrn(string urn)
{
_logger.LogInformation($"Attempting to get Performance Data for URN {urn}");
_logger.LogInformation($"Attempting to get Performance Data for Unique Reference Number (URN) {urn}");
var performanceData = _getKeyStagePerformanceByUrn.Execute(urn);
if (performanceData == null)
{
_logger.LogInformation($"No Performance Data found for URN {urn}");
_logger.LogInformation($"No Performance Data found for Unique Reference Number (URN) {urn}");
return NotFound();
}
_logger.LogInformation($"Returning Performance Data for URN {urn}");
_logger.LogInformation($"Returning Performance Data for Unique Reference Number (URN) {urn}");
_logger.LogDebug(JsonSerializer.Serialize<EducationalPerformanceResponse>(performanceData));
return Ok(performanceData);
}
Expand Down
16 changes: 8 additions & 8 deletions TramsDataApi/Controllers/TrustsController.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,27 +29,27 @@ public TrustsController(IGetTrustByUkprn getTrustByUkprn, ISearchTrusts searchTr
}

/// <summary>
/// Retrieves a Trust by its UKPRN.
/// Retrieves a Trust by its UK Provider Reference Number (UKPRN).
/// </summary>
/// <param name="ukprn">The UKPRN identifier.</param>
/// <param name="ukprn">The UK Provider Reference Number (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.")]
[SwaggerOperation(Summary = "Retrieve Trust by UK Provider Reference Number (UKPRN)", Description = "Returns a Trust identified by UK Provider Reference Number (UKPRN).")]
[SwaggerResponse(200, "Successfully found and returned the Trust.")]
[SwaggerResponse(404, "Trust with specified UKPRN not found.")]
[SwaggerResponse(404, "Trust with specified UK Provider Reference Number (UKPRN) not found.")]
public ActionResult<TrustResponse> GetTrustByUkprn(string ukprn)
{
_logger.LogInformation($"Attempting to get trust by UKPRN {ukprn}");
_logger.LogInformation($"Attempting to get trust by UK Provider Reference Number (UKPRN) {ukprn}");
var trust = _getTrustByUkprn.Execute(ukprn);

if (trust == null)
{
_logger.LogInformation($"No trust found for UKPRN {ukprn}");
_logger.LogInformation($"No trust found for UK Provider Reference Number (UKPRN) {ukprn}");
return NotFound();
}

_logger.LogInformation($"Returning trust found by UKPRN {ukprn}");
_logger.LogInformation($"Returning trust found by UK Provider Reference Number (UKPRN) {ukprn}");
_logger.LogDebug(JsonSerializer.Serialize(trust));
return Ok(trust);
}
Expand All @@ -58,7 +58,7 @@ public ActionResult<TrustResponse> GetTrustByUkprn(string ukprn)
/// Searches for Trusts based on query parameters.
/// </summary>
/// <param name="groupName">Name of the group.</param>
/// <param name="ukPrn">UKPRN identifier.</param>
/// <param name="ukPrn">UK Provider Reference Number (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>
Expand Down
23 changes: 20 additions & 3 deletions TramsDataApi/Controllers/V2/BaselineTrackerController.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,20 @@
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.V2
{
/// <summary>
/// Manages baseline tracker-related operations.
/// </summary>
[ApiVersion("2.0")]
[ApiController]
[Route("v{version:apiVersion}/basline-tracker")]
[SwaggerTag("Operations related to Baseline Tracking")]
public class BaselineTrackerController : ControllerBase
{
private readonly ILogger<BaselineTrackerController> _logger;
Expand All @@ -28,9 +33,21 @@ public BaselineTrackerController(ILogger<BaselineTrackerController> logger,
_getAllBBaselineTrackerRequestByStatus = getAllBBaselineTrackerRequestByStatus;
}

[HttpGet]
[MapToApiVersion("2.0")]
public ActionResult<ApiResponseV2<BaselineTrackerResponse>> Get(
/// <summary>
/// Retrieves a paginated list of baseline trackers.
/// </summary>
/// <param name="states">Comma-separated list of states to filter by.</param>
/// <param name="page">The page number to return.</param>
/// <param name="count">The number of items per page.</param>
/// <returns>A paginated ApiResponse containing BaselineTrackerResponse objects.</returns>
[HttpGet]
[MapToApiVersion("2.0")]
[SwaggerOperation(
Summary = "Retrieve Baseline Trackers",
Description = "Returns a paginated list of baseline trackers, optionally filtered by states."
)]
[SwaggerResponse(200, "Successfully found and returned the list of baseline trackers.")]
public ActionResult<ApiResponseV2<BaselineTrackerResponse>> Get(
[FromQuery] string states = null,
[FromQuery] int page = 1,
[FromQuery] int count = 50)
Expand Down
25 changes: 25 additions & 0 deletions TramsDataApi/Controllers/V2/TrustsController.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,20 @@
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.V2
{
/// <summary>
/// Manages trusts operations.
/// </summary>
[ApiVersion("2.0")]
[ApiController]
[Route("v{version:apiVersion}/")]
[SwaggerTag("Operations related to Trusts")]
public class TrustsController : ControllerBase
{
private readonly IGetTrustByUkprn _getTrustByUkPrn;
Expand All @@ -27,8 +32,16 @@ public TrustsController(IGetTrustByUkprn getTrustByUkPrn, ISearchTrusts searchTr
_logger = logger;
}

/// <summary>
/// Searches for trusts based on given criteria.
/// </summary>
/// <remarks>
/// Search can be performed using the groupName, UK Provider Reference Number (UKPRN), and companiesHouseNumber parameters.
/// </remarks>
[HttpGet("trusts")]
[MapToApiVersion("2.0")]
[SwaggerOperation(Summary = "Search Trusts", Description = "Search for trusts using the specified parameters.")]
[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)
{
Expand All @@ -54,9 +67,15 @@ public ActionResult<ApiResponseV2<TrustSummaryResponse>> SearchTrusts(string gro
return new OkObjectResult(response);
}

/// <summary>
/// Retrieves a specific trust by UK Provider Reference Number (UKPRN).
/// </summary>
[HttpGet]
[Route("trust/{ukprn}")]
[MapToApiVersion("2.0")]
[SwaggerOperation(Summary = "Get Trust By UK Provider Reference Number (UKPRN)", Description = "Retrieve a single trust by its UK Provider Reference Number (UKPRN).")]
[SwaggerResponse(200, "Successfully retrieved the trust.")]
[SwaggerResponse(404, "The trust was not found.")]
public ActionResult<ApiSingleResponseV2<TrustResponse>> GetTrustByUkPrn(string ukprn)
{
_logger.LogInformation("Attempting to get trust by UKPRN {prn}", ukprn);
Expand All @@ -75,9 +94,15 @@ public ActionResult<ApiSingleResponseV2<TrustResponse>> GetTrustByUkPrn(string u
return new OkObjectResult(response);
}

/// <summary>
/// Retrieves multiple trusts by their UK Provider Reference Numbers (UKPRNs).
/// </summary>
[HttpGet]
[Route("trusts/bulk")]
[MapToApiVersion("2.0")]
[SwaggerOperation(Summary = "Get Trusts By UK Provider Reference Numbers (UKPRNs)", Description = "Retrieve multiple trusts by their UK Provider Reference Numbers (UKPRNs).")]
[SwaggerResponse(200, "Successfully retrieved the trusts.")]
[SwaggerResponse(404, "The trusts were not found.")]
public ActionResult<ApiResponseV2<TrustResponse>> GetByUkprns([FromQuery] GetTrustsByUkprnsRequest request)
{
var commaSeparatedRequestUkprns = string.Join(",", request.Ukprns);
Expand Down

0 comments on commit aef9ff3

Please sign in to comment.