FastEndpoints配置GET请求Query参数无法在Scalar OpenApi文档正确展示

一、修复路径参数被识别为请求体的问题 #

出现这个问题的核心原因是FastEndpoints的参数绑定标记缺失，导致OpenAPI元数据生成错误，进而被Scalar误判为请求体参数。

正确实现方式1：直接从路由获取参数 #

public class TestEndpoint : EndpointWithoutRequest
{
    public override void Configure()
    {
        Get("/api/parent/{ParentId}/child/{ChildId}"); // 路由模板明确声明路径参数
        AllowAnonymous();
    }

    public override async Task HandleAsync(CancellationToken ct)
    {
        // 直接从路由上下文读取参数
        var parentId = Route<int>("ParentId");
        var childId = Route<int>("ChildId");

        await SendOkAsync(new { ParentId = parentId, ChildId = childId }, ct);
    }
}

正确实现方式2：使用DTO绑定路径参数 #

如果需要用DTO接收参数，必须给对应属性添加[RouteParam]标记，明确告知FastEndpoints这是路径参数：

public class TestRequest
{
    [RouteParam]
    public int ParentId { get; set; }

    [RouteParam]
    public int ChildId { get; set; }
}

public class TestEndpoint : Endpoint<TestRequest>
{
    public override void Configure()
    {
        Get("/api/parent/{ParentId}/child/{ChildId}");
        AllowAnonymous();
    }

    public override async Task HandleAsync(TestRequest req, CancellationToken ct)
    {
        await SendOkAsync(new { req.ParentId, req.ChildId }, ct);
    }
}

关键注意点：路由模板中的参数名称必须和代码中读取的名称（或DTO属性名）完全一致，否则元数据生成会出错。

二、配置Query参数显示在Scalar的Query区域 #

要让Query参数出现在Scalar的Query标签页而非Variables区域，需要用[QueryParam]标记参数，并确保路由模板中不包含这些参数。

实现示例 #

public class TestQueryRequest
{
    [QueryParam] // 标记为Query参数
    public string? SearchKeyword { get; set; }

    [QueryParam]
    public int PageIndex { get; set; } = 1;

    [QueryParam]
    public int PageSize { get; set; } = 20;
}

public class TestQueryEndpoint : Endpoint<TestQueryRequest>
{
    public override void Configure()
    {
        Get("/api/data/list"); // 路由模板不包含Query参数
        AllowAnonymous();
    }

    public override async Task HandleAsync(TestQueryRequest req, CancellationToken ct)
    {
        // 直接使用DTO中的Query参数
        await SendOkAsync(new { req.SearchKeyword, req.PageIndex, req.PageSize }, ct);
    }
}

效果：Scalar会根据OpenAPI元数据，将这些参数展示在Query区域，测试时填写后会自动以?SearchKeyword=xxx&PageIndex=1的格式拼接在URL后传递。

三、基础配置校验 #

确保Program.cs中已正确启用FastEndpoints的OpenAPI和Scalar支持：

// 服务注册
builder.Services.AddFastEndpoints()
    .AddOpenApi();

// 中间件配置
app.UseFastEndpoints()
    .UseOpenApi()
    .UseScalar();

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