I'm working on a microservice which is a proxy/façade for Personio, allowing us to filter and otherwise manipulate their API's own responses.
We have a couple endpoints which will allow authorized users to receive Personio's responses after redacting them. These endpoints allow the consumer to include any query parameters and forward them to Personio "as-is", for Personio to decide whether it supports the parameter, ignores the parameter, or causes the server to vomit.
We use Swagger to document our own endpoints.
As we get the consumer's query parameters from Request.Query at a deeper level within the code, for example:
/// <summary>
/// This endpoint acts as a proxy for Personio's Employee records, filtering the results only to include Montage employees..
/// Any query parameters passed to this endpoint will be passed "as-is" to Personio.
/// At this time (2021 December 22), Personio only supports "limit", "offset", and "email" on the Employee endpoint
/// While Personio itself does not require the "limit" parameter, this is known to cause performance issues, so if the consumer do not
/// provide this, we will set this to the maximum value of 200.
/// @see also: https://developer.personio.de/reference#employees-1
/// </summary>
[Authorize(Roles = MontageReadRole)]
[ProducesResponseType(typeof(PagedList<JObject>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(List<ErrorMessage>), StatusCodes.Status403Forbidden)]
[HttpGet("Employees/Montage")]
public Task<IActionResult> GetMontageEmployees(CancellationToken cancellationToken) =>
GetMontageData(_personioEmployeeService.GetMontageEmployees, cancellationToken);
private async Task<IActionResult> GetMontageData<T>(Func<IQueryCollection, CancellationToken, TryAsync<RequestResponse<T>>> getData, CancellationToken cancellationToken)
{
try
{
IActionResult result = null;
_ = await getData(Request.Query, cancellationToken)
.Match(
Succ: response =>
result = Ok(response),
Fail: exception =>
result = _controllerErrorHandler.CreateBadRequestObject(new()
{
Status = StatusCodes.Status422UnprocessableEntity,
Type = "Unprocessable Entity",
Detail = exception.Message
})
)
.ConfigureAwait(false);
return result;
}
catch (UnauthorizedAccessException ex)
{
return _controllerErrorHandler.CreateAuthenticationFailureResponse(ex);
}
}
... they are not part of the endpoint's method signature, so Swagger has no reasonable way of knowing that this is supported.
Is there any way (e.g. through an attribute) I can allow consumers to include additional query parameters?
Or, at the very least, is there some way I can include some sort of description on the endpoint to tell the consumer "hey, we support this!"? (FYI, the <summary> above does not appear on the swagger page.)
