FastEndpoints在.NET 9迁移后NoContent端点生成错误Swagger Schema的问题分析

在将项目迁移到.NET 9后，使用FastEndpoints框架的开发人员发现了一个与Swagger文档生成相关的问题。当端点返回NoContent结果时，生成的Swagger Schema会出现不正确的格式。

问题现象

在.NET 9环境下，返回NoContent的端点会在Swagger文档中生成一个200状态码的响应定义，其格式如下：

"200": {
    "description": "Success",
    "content": {
        "text/plain": null
    }
}

这种格式存在两个明显问题：

1. 不应该为204 NoContent响应生成200状态码的定义
2. "text/plain": null的格式既不符合常规也不符合规范

技术背景

在HTTP协议中，204 NoContent响应表示服务器成功处理了请求，但不需要返回任何实体内容。这与200 OK响应有本质区别，后者通常需要包含响应体内容。

FastEndpoints框架通过SendNoContentAsync方法支持这种响应类型，但在.NET 9环境下，Swagger文档生成器出现了异常行为。

临时解决方案

开发团队提供了一个临时解决方案，可以通过以下代码清除默认的200响应生成：

Description(b => b.ClearDefaultProduces(200));

根本原因

这个问题实际上源于.NET 9 SDK中的一个已知bug。微软ASP.NET Core团队已经确认了这个问题，但尚未发布修复版本。

框架修复

FastEndpoints团队在v5.31.0.15-beta版本中加入了临时解决方案，以规避.NET 9 SDK的这个bug。开发人员可以升级到这个版本或更高版本来解决此问题。

最佳实践建议

对于需要返回NoContent响应的端点，建议：

1. 明确设置204状态码的响应定义
2. 避免依赖框架的默认行为
3. 定期检查框架更新，以便在.NET团队修复底层问题后可以移除临时解决方案

这个问题展示了框架与底层平台之间的复杂交互关系，也提醒开发人员在升级主要平台版本时需要全面测试API文档生成功能。