FastEndpoints中路由参数类型约束的Swagger支持解析

在ASP.NET Core Web API开发中，路由参数约束是一个非常有用的特性，它允许开发者在路由模板中直接指定参数的类型要求。FastEndpoints作为一款高性能的API框架，同样支持这一特性。本文将深入探讨如何在FastEndpoints中正确配置路由参数约束，并使其在Swagger文档中正确显示参数类型。

路由参数约束的基本概念

路由参数约束允许开发者在路由模板中直接指定参数的类型，例如：

Get("/users/{userId:int}");

这样的约束不仅能在路由匹配时进行参数类型验证，还能在Swagger文档中正确显示参数类型，为API使用者提供更准确的文档信息。

FastEndpoints中的实现机制

FastEndpoints从5.25版本开始，全面支持路由参数约束在Swagger文档中的正确显示。要实现这一功能，需要注意以下几个关键配置点：

1. 版本要求：必须使用FastEndpoints 5.25或更高版本，早期版本可能无法正确显示参数类型。

2. 属性命名策略：FastEndpoints默认使用camelCase命名策略，这会影响路由参数的匹配：

   • 如果保持默认设置，路由参数应使用camelCase命名，如{userId:int}
   • 若要禁用命名策略，可以配置：

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

     或者：

     .UseFastEndpoints(c => c.Serializer.Options.PropertyNamingPolicy = null)
     

实际应用示例

以下是一个完整的配置示例，展示如何确保路由参数类型在Swagger中正确显示：

// 在Program.cs或Startup.cs中配置
builder.Services
    .AddFastEndpoints()
    .SwaggerDocument(d => {
        d.UsePropertyNamingPolicy = false; // 禁用命名策略
    });

// 端点定义
public class UserEndpoint : EndpointWithoutRequest
{
    public override void Configure()
    {
        Get("/users/{userId:int}"); // 使用路由参数约束
        AllowAnonymous();
    }

    public override async Task HandleAsync(CancellationToken ct)
    {
        var userId = Route<int>("userId");
        // 处理逻辑...
    }
}

常见问题解决

如果发现Swagger中参数类型仍然显示为string，请检查以下方面：

1. 确认使用的是FastEndpoints 5.25或更高版本
2. 检查是否配置了正确的属性命名策略
3. 确保路由参数名称与约束之间没有空格
4. 验证约束语法是否正确（如int而不是integer）

最佳实践建议

1. 一致性：在整个项目中保持路由参数命名风格一致，要么全部使用camelCase，要么全部禁用命名策略。
2. 显式优于隐式：即使框架能自动推断类型，也建议显式声明路由约束，提高代码可读性。
3. 文档补充：虽然Swagger能显示基本类型信息，但对于复杂约束条件，建议在端点描述中补充说明。

通过正确配置FastEndpoints的路由参数约束，开发者可以构建出类型安全、文档完善的API接口，提升整体开发体验和API可用性。