FastEndpoints项目中的OpenAPI参数路由问题解析

问题背景

在使用FastEndpoints框架与.NET 9结合开发API时，开发者遇到了一个关于OpenAPI文档生成的问题。具体表现为：当创建包含路由参数的端点时，这些路由参数没有被正确地添加到OpenAPI定义中。

技术细节分析

配置环境

开发者采用了以下配置方式：

1. 在Program.cs中：

   • 添加了FastEndpoints服务
   • 配置了OpenAPI支持
   • 设置了API版本控制和路由前缀

2. 创建了一个示例端点：

   • 定义了一个GET路由"/weatherforecast/{Test}"
   • 使用了EndpointWithoutRequest基类
   • 在处理器中通过Route("Test")获取路由参数

问题现象

尽管端点配置中明确定义了路由参数"{Test}"，但在生成的OpenAPI文档中，这个参数却没有被包含。这种情况在使用DTO和不使用DTO映射请求时都会出现。

解决方案

根本原因

问题的核心在于FastEndpoints框架目前尚未支持微软新推出的OpenAPI包。FastEndpoints团队提供了专门的Swagger集成包(FastEndpoints.Swagger)，这个包是基于NSwag实现的，而不是使用已被弃用的Swashbuckle。

正确配置方式

要解决这个问题，开发者应该：

1. 必须使用FastEndpoints.Swagger包，这是框架的NSwag集成包
2. 可以自由选择任何Swagger UI库与FastEndpoints.Swagger配合使用
3. 避免尝试使用微软的新OpenAPI包或已弃用的Swashbuckle

配置示例

正确的配置应该包含以下关键点：

// 添加FastEndpoints和Swagger支持
services.AddFastEndpoints()
        .AddSwaggerDoc(); // 使用FastEndpoints.Swagger提供的方法

// 配置端点
app.UseFastEndpoints(c => {
    c.Versioning.Prefix = "v";
    c.Versioning.DefaultVersion = 1;
    c.Versioning.PrependToRoute = true;
    c.Endpoints.RoutePrefix = "api";
});

// 配置Swagger UI
app.UseSwaggerGen();

技术建议

1. 版本兼容性：在使用新版本的.NET时，要特别注意框架依赖项的兼容性
2. 文档生成：对于OpenAPI/Swagger文档生成，应该遵循框架推荐的方式
3. 参数定义：确保路由参数在端点和DTO中都有明确定义
4. 测试验证：生成文档后，应该实际测试API端点以确保参数传递正常工作

总结

在FastEndpoints框架中处理OpenAPI文档生成时，关键是要使用框架提供的专用Swagger集成包，而不是尝试使用微软的新OpenAPI包。这种设计选择确保了文档生成的稳定性和一致性，同时也为开发者提供了灵活的UI展示选项。通过遵循框架推荐的最佳实践，可以避免路由参数在OpenAPI文档中缺失的问题。