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

在ASP.NET Core项目中使用OpenAPI/Swagger生成API文档时，开发人员经常需要为模型属性设置默认值。本文将通过一个实际案例，深入探讨如何在ASP.NET Core中正确配置模型属性的默认值，使其能够正确反映在OpenAPI文档中。

问题背景

在ASP.NET Core项目中，当我们定义API模型时，可能会为某些属性设置默认值。例如：

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

在这个例子中，ContentType属性设置了默认值"text"。然而，当使用OpenAPI生成API文档时，这个默认值并不会自动出现在生成的文档中。

参数默认值 vs 模型属性默认值

值得注意的是，对于API方法参数中的默认值，OpenAPI能够正确识别并展示：

app.MapPost("translation", (TranslationRequest request, string source = "test") =>
{
   // ...
});

在这个例子中，source参数的默认值"test"会正确显示在OpenAPI文档中。这是因为方法参数的默认值是在编译时就能确定的元数据信息。

为什么模型属性默认值不被自动识别

模型属性的默认值（如= "text"）不被自动识别到OpenAPI文档中，主要有以下技术原因：

1. 运行时行为：属性默认值实际上是构造函数代码的一部分，OpenAPI生成器无法在静态分析阶段确定这些值

2. AoT兼容性：为了支持原生AoT编译，OpenAPI生成器需要避免复杂的运行时反射

3. 构造复杂性：对于没有默认构造函数的对象或复杂对象图，确定属性默认值会变得非常困难

解决方案：使用DefaultValue特性

要让模型属性的默认值出现在OpenAPI文档中，正确的做法是使用[DefaultValue]特性：

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

这样配置后，OpenAPI文档将正确显示ContentType属性的默认值为"text"。

最佳实践

1. 一致性：对于所有需要显示默认值的模型属性，都应该使用[DefaultValue]特性

2. 保持同步：确保特性中的默认值与代码中赋值的默认值一致，避免混淆

3. 文档优先：考虑采用文档优先的API开发方式，先定义OpenAPI规范，再生成代码

4. 代码可读性：即使默认值会出现在文档中，代码中保留默认值赋值也是个好习惯，提高代码可读性

总结

在ASP.NET Core项目中，OpenAPI文档生成器不会自动识别模型属性的默认值赋值。为了确保API文档能准确反映默认值，开发人员应该使用[DefaultValue]特性来显式声明这些默认值。这种做法既保持了代码的清晰性，又能生成准确的API文档，为API消费者提供更好的开发体验。

通过理解这一机制，开发人员可以更有效地利用ASP.NET Core的OpenAPI集成功能，创建出更专业、更易用的API文档。