1

我正在开发一个微服务，它是 Personio 的代理/外观，允许我们过滤和以其他方式操作他们的 API 自己的响应。

我们有几个端点允许授权用户在编辑后接收 Personio 的响应。这些端点允许消费者包含任何查询参数并将它们“按原样”转发给 Personio，以便 Personio 决定它是否支持参数、忽略参数或导致服务器呕吐。

我们使用 Swagger 来记录我们自己的端点。

当我们从代码的更深层次获取消费者的查询参数Request.Query时，例如：

    /// <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);
        }
    }

...它们不是端点方法签名的一部分，因此 Swagger 无法合理地知道它是否受支持。

有什么方法（例如通过属性）我可以允许消费者包含额外的查询参数？

或者，至少，有什么方法可以在端点上包含某种描述来告诉消费者“嘿，我们支持这个！”？（仅供参考，<summary>以上内容不会出现在招摇页面上。）

4

0 回答 0