FastEndpoints项目中Swagger文档生成对请求与响应模型的差异化处理

在FastEndpoints项目中，开发者可能会遇到Swagger文档生成时请求模型(Request)与响应模型(Response)在可空性处理上的差异问题。本文将深入分析这一现象的原因，并提供解决方案。

问题现象

当使用FastEndpoints框架开发API时，开发者可能会注意到：

1. 对于请求模型(Request)，需要使用string?语法显式标记可空属性
2. 对于响应模型(Response)，即使没有使用?标记，属性也会默认显示为可空(nullable:true)
3. 使用[Required]属性虽然可以标记必填字段，但会以验证标记(红色*)形式显示，而非移除nullable:true

根本原因

这一现象的核心原因在于项目级别的Nullable特性设置。当项目禁用Nullable特性时：

1. 请求模型的文档生成仍能正确识别可空性
2. 响应模型的文档生成会默认所有属性为可空

解决方案

FastEndpoints提供了专门的配置方法来控制这一行为：

builder.Services.SwaggerDocument(o => 
    o.DocumentSettings = d => d.MarkNonNullablePropsAsRequired());

启用此设置后，Swagger文档将正确反映模型的可空性：

• 非可空属性(如public string Id {get;set;})将被标记为必需
• 可空属性(如public string? Id {get;set;})将显示nullable:true

最佳实践

1. 保持项目Nullable特性启用：这是现代C#项目的推荐做法，能提供更好的静态分析支持
2. 明确区分请求和响应模型：即使结构相同，也应分别定义请求和响应DTO
3. 使用显式可空标记：即使Nullable特性启用，显式标记可空性也能提高代码可读性
4. 统一文档生成配置：确保所有环境的Swagger生成配置一致

示例模型

// 请求模型
sealed class Request
{
    public string? Id { get; set; }  // 显式标记为可空
}

// 响应模型
sealed class Response
{
    public string Id { get; set; }  // 非可空属性
}

启用正确配置后，生成的Swagger文档将准确反映这些差异，为API使用者提供清晰的接口契约。

通过理解FastEndpoints的这一设计特点和正确配置，开发者可以生成更精确的API文档，提高前后端协作效率。