FastEndpoints框架中Swagger路由参数类型解析问题解析

在使用FastEndpoints框架开发Web API时，开发者可能会遇到Swagger文档无法正确显示路由参数类型的问题。本文将深入分析该问题的成因，并提供多种解决方案。

问题现象

当开发者使用EndpointWithoutRequest基类创建端点时，在Swagger文档中可能会出现以下情况：

1. 路由参数完全缺失
2. 参数类型默认为字符串而非实际类型（如int）

典型示例代码如下：

Get("/users/{UserId}");
int userId = Route<int>("UserId");

根本原因分析

经过技术团队排查，发现该问题主要由两个因素导致：

1. 属性命名策略冲突：最新版FastEndpoints会将JSON属性命名策略应用到Swagger路由参数上，导致大小写敏感问题

2. 类型推断机制限制：框架目前无法直接从路由约束（如{UserId:int}）推断参数类型，必须通过请求DTO来明确指定

解决方案

方案一：禁用属性命名策略

在Swagger配置中关闭属性命名策略：

.SwaggerDocument(x => x.UsePropertyNamingPolicy = false);

方案二：保持命名一致性

确保路由模板和参数获取使用相同命名规范：

Get("/users/{userId}");  // 路由模板
var userId = Route<int>("userId");  // 参数获取

方案三：使用请求DTO（推荐）

这是最可靠的解决方案，能确保Swagger正确识别参数类型：

sealed class UserRequest
{
    public int UserId { get; set; }
}

sealed class GetUserEndpoint : Endpoint<UserRequest>
{
    public override void Configure()
    {
        Get("/users/{UserId}");
    }
    
    public override Task HandleAsync(UserRequest req, CancellationToken ct)
    {
        // 直接使用req.UserId
    }
}

最佳实践建议

1. 项目初始化检查：确保正确配置了端点发现机制，包括：

   • 端点类必须为sealed
   • 必须继承自FastEndpoints的基类
   • 项目引用必要的NuGet包

2. Swagger集成：推荐使用框架内置的Swagger支持，而非Swashbuckle

3. 类型安全：对于强类型路由参数，始终使用请求DTO来确保类型安全

技术细节补充

当使用路由约束（如{id:int}）时，虽然运行时可以正确解析类型，但Swagger文档生成阶段需要明确的类型声明。这是因为：

1. 路由约束是运行时特性
2. Swagger文档生成是设计时/编译时行为
3. 请求DTO提供了编译时可用的类型信息

通过采用本文推荐的解决方案，开发者可以确保API文档的准确性和一致性，同时保持代码的清晰和可维护性。