Swashbuckle 5.0.0-rc2生成OpenAPI规范出现参数空默认值异常

可能的原因 #

• 项目注册的自定义Schema/操作过滤器逻辑异常：你提到的自定义Schema ID生成逻辑通常会配套注册ISchemaFilter或IOperationFilter，很多低版本的自定义实现会统一给所有Schema添加default字段，未做空值判断，哪怕代码中没有显式定义默认值，也会自动赋值为对应类型的空值。
• 可空引用类型配置兼容问题：如果问题项目开启了<Nullable>enable</Nullable>可空引用类型，Swashbuckle 5.0.0-rc2版本对可空引用类型的支持存在缺陷，会错误将非可空引用类型、值类型的默认值映射为空字符串。
• 全局序列化配置冲突：如果项目的System.Text.Json或Newtonsoft.Json全局配置中设置了DefaultValueHandling.Include这类规则，Swashbuckle会读取该配置，强制为所有参数Schema添加default属性。

解决方案 #

快速兜底方案 #

直接注册操作过滤器移除所有无效的空默认值，适配Swashbuckle 5.0.0-rc2版本的代码如下：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Linq;

public class RemoveEmptyDefaultValueFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        foreach (var parameter in operation.Parameters ?? Enumerable.Empty<OpenApiParameter>())
        {
            // 移除空字符串、空值的default属性
            if (parameter.Schema.Default is OpenApiString strVal && string.IsNullOrEmpty(strVal.Value))
            {
                parameter.Schema.Default = null;
            }
        }
    }
}

在Swagger配置中注册该过滤器即可：

services.AddSwaggerGen(c =>
{
    // 保留你原有配置
    c.OperationFilter<RemoveEmptyDefaultValueFilter>();
});

精准排查方案 #

1. 检查AddSwaggerGen配置中的所有自定义过滤器，排查是否有强制给Schema.Default赋值的逻辑，添加判断仅当存在显式默认值时才赋值。
2. 若项目开启了可空引用类型，在配置中添加c.SupportNonNullableReferenceTypes();修复类型识别异常。
3. 检查序列化全局配置，若存在全局默认值包含规则，可在Swagger配置中添加c.IgnoreIsSpecifiedMembers();屏蔽序列化配置的干扰。

内容的提问来源于stack exchange，提问作者Arcord