ASP.NET Core OpenAPI 文档中模型默认值的配置技巧

在ASP.NET Core项目中使用OpenAPI/Swagger生成API文档时，开发人员经常会遇到模型属性默认值无法正确显示的问题。本文将深入探讨这一现象的原因，并提供有效的解决方案。

问题现象

当我们在C#模型中为属性设置默认值时，例如：

public sealed class TranslationRequest
{
    public required string Text { get; set; }
    public string? ContentType { get; set; } = "text";
    public string? Context { get; set; }
}

期望在生成的OpenAPI文档中看到ContentType属性的默认值为"text"，但实际上文档中并没有显示这一默认值。

原因分析

这种现象源于ASP.NET Core OpenAPI文档生成机制的设计考虑：

1. 运行时与编译时的差异：属性初始化器(= "text")是编译时行为，而OpenAPI文档生成是在运行时进行的
2. AOT兼容性：为了支持原生AOT编译，避免复杂的运行时反射
3. 构造函数逻辑：属性初始化器本质上属于构造函数逻辑的一部分，文档生成器无法轻易捕获

解决方案

正确的做法是使用DefaultValue特性来显式声明默认值：

public sealed class TranslationRequest
{
    public required string Text { get; set; }
    
    [DefaultValue("text")]
    public string? ContentType { get; set; } = "text";
    
    public string? Context { get; set; }
}

这种方法有以下优势：

1. 明确意图：清晰地向文档生成器表明这是API契约的一部分
2. 可维护性：即使属性初始化逻辑变更，API文档依然保持稳定
3. 兼容性：与各种编译模式和运行时环境兼容

对比说明

配置方式	OpenAPI文档显示	适用场景
属性初始化器	不显示默认值	内部逻辑默认值
DefaultValue特性	显示默认值	API契约默认值
参数默认值	自动显示	方法参数默认值

最佳实践

1. 对于公开的API模型，优先使用DefaultValue特性
2. 保持属性初始化器和DefaultValue特性值一致
3. 对于简单的DTO，可以只使用DefaultValue特性
4. 对于方法参数默认值，直接使用C#语法即可，文档生成器会自动处理

通过理解这些原理和采用正确的配置方法，开发者可以确保ASP.NET Core项目的OpenAPI文档准确反映API的设计意图，为API消费者提供更清晰的接口说明。