FastEndpoints 中 FromBody 属性导致 Swagger 文档生成问题的分析与解决

在 FastEndpoints 框架使用过程中，开发者发现了一个关于 Swagger 文档生成的特殊现象：当请求 DTO 中包含使用 [FromBody] 标记的属性时，即使已经设置了 RemoveEmptyRequestSchema = True，这些 DTO 仍然会出现在生成的 Swagger 文档中。

问题背景

FastEndpoints 框架提供了多种请求参数绑定方式，包括 [FromBody]、[FromClaims] 等属性标记。开发者通常有两种使用模式：

1. 在主 API 契约类上使用 [FromHeader]、[FromQuery] 等标记，让未标记的属性默认从请求体绑定
2. 为每个端点定义专门的请求 DTO，显式使用 [From*] 属性指定每个参数的绑定来源

采用第二种模式时，开发者发现即使端点定义正确引用了 [FromBody] 属性的类型，父级 DTO 类型仍然会出现在 Swagger 文档中，这不符合预期行为。

问题分析

问题的核心在于 Swagger 文档生成逻辑对 [FromBody] 标记属性的处理方式。当满足以下条件时会出现此问题：

1. 请求 DTO 中包含 [FromBody] 标记的属性
2. 配置了 RemoveEmptyRequestSchema = True
3. 其他非 [FromBody] 属性被正确地从 Swagger 文档中移除

在这种情况下，框架本应完全移除父级 DTO 的架构定义，但实际上却保留了它，导致 Swagger 文档中出现了不必要的类型定义。

解决方案

FastEndpoints 团队在 v5.29.0.6-beta 版本中修复了这个问题。修复后的行为是：

• 当请求 DTO 仅包含 [FromBody] 标记属性时
• 且配置了 RemoveEmptyRequestSchema = True
• 父级 DTO 架构将不再出现在生成的 Swagger 规范中

这个改动使得 Swagger 文档更加简洁，更符合开发者的预期，特别是对于那些喜欢为每个端点定义专门请求 DTO 的开发模式。

最佳实践建议

基于这个问题的解决，我们可以总结出一些 FastEndpoints 的使用建议：

1. 显式使用 [From*] 属性标记参数来源是一个良好的实践，可以提高代码的可读性
2. 为每个端点定义专门的请求 DTO 有助于分离关注点，避免前端契约与后端实现的混淆
3. 保持 FastEndpoints 框架的及时更新，以获取最新的功能改进和问题修复
4. 合理使用 RemoveEmptyRequestSchema 配置可以使生成的 API 文档更加简洁

这个问题的解决体现了 FastEndpoints 框架对开发者体验的持续关注，也展示了开源社区快速响应和解决问题的能力。