FastEndpoints中GET请求请求对象无法绑定到Query参数问题

问题原因 #

FastEndpoints虽通过[QueryParam]标记参数应从Query绑定，但NSwag默认会将GET请求的复杂DTO类型识别为请求体，导致Swagger界面显示请求体输入区域而非Query参数项。

解决方法 #

方法1：在端点配置中显式指定参数绑定源 #

在GetRoles端点的Configure方法中添加绑定配置，明确告知FastEndpoints从Query参数绑定请求对象：

public override void Configure()
{
    Get("roles");
    Options(o => o.WithTags("Roles"));
    // 显式绑定Query参数到请求对象
    RequestBinder(r => r.Query<GetRolesRequest>());
}

方法2：配置NSwag自动拆分复杂类型为Query参数 #

在AddSwaggerDocument的配置中添加自定义操作处理器，自动将GET请求的复杂体参数转换为Query参数：

.AddSwaggerDocument(c =>
{
    c.DocumentName = "v1";
    c.Title = "OctuFit API documentation";
    c.Version = "v1";
    c.Description = "OctuFit API documentation";

    // 现有JWT配置...

    // 添加自定义处理器处理GET请求的复杂参数
    c.OperationProcessors.Add(new NSwag.Generation.Processors.IOperationProcessor
    {
        Process = (context) =>
        {
            if (context.OperationDescription.HttpMethod == NSwag.OpenApiHttpMethod.Get)
            {
                // 移除所有Body类型的参数
                var bodyParams = context.OperationDescription.Operation.Parameters
                    .Where(p => p.Kind == NSwag.OpenApiParameterKind.Body)
                    .ToList();

                foreach (var bodyParam in bodyParams)
                {
                    context.OperationDescription.Operation.Parameters.Remove(bodyParam);

                    // 生成参数的Schema并拆分为Query参数
                    var schema = context.SchemaGenerator.GenerateSchema(bodyParam.Schema.Type, context.SchemaResolver);
                    foreach (var prop in schema.Properties)
                    {
                        context.OperationDescription.Operation.Parameters.Add(new NSwag.OpenApiParameter
                        {
                            Name = prop.Key,
                            Kind = NSwag.OpenApiParameterKind.Query,
                            Schema = prop.Value,
                            IsRequired = bodyParam.IsRequired && schema.Required?.Contains(prop.Key) == true
                        });
                    }
                }
            }
            return true;
        }
    });
})

方法3：确认[QueryParam]属性的命名空间 #

确保PaginationRequestBase中使用的[QueryParam]是FastEndpoints提供的属性，添加正确命名空间：

using FastEndpoints; // 必须添加此命名空间

public class PaginationRequestBase
{
    // ... 现有代码 ...
}

验证 #

修改完成后重启API，打开Swagger界面，GET /api/roles接口应显示Page、PageSize、Search三个Query参数输入项，而非请求体区域。

内容的提问来源于stack exchange，提问作者DrXSsive