Swashbuckle.AspNetCore中嵌套记录类型的非空引用类型支持问题分析

Swashbuckle.AspNetCore作为.NET生态中广泛使用的Swagger/OpenAPI文档生成工具，在处理C#记录类型(record)时存在一个值得注意的问题：当记录类型嵌套定义时，其非空引用类型(nullable reference types)的支持会出现异常。

问题现象

在Swashbuckle.AspNetCore 6.5.0版本中，当开发者使用嵌套定义的记录类型时，即使明确标记了非空引用类型，生成的OpenAPI/Swagger文档也会错误地将这些属性标记为可空。具体表现为：

1. 对于非嵌套的记录类型，Swashbuckle能够正确识别非空属性
2. 对于嵌套定义的记录类型，所有属性都会被错误地标记为可空

技术背景

C# 8.0引入的非空引用类型特性允许开发者在编译时检查可能的空引用异常。当启用此功能时，引用类型默认被视为不可为空，必须显式使用?后缀标记可为空的类型。

Swashbuckle.AspNetCore通过SupportNonNullableReferenceTypes()方法支持这一特性，它能够：

• 自动识别类型定义中的非空标记
• 在生成的OpenAPI文档中正确反映这些约束
• 帮助API消费者了解哪些字段是必填的

问题复现

通过以下两种记录类型定义的对比可以清晰复现问题：

// 非嵌套记录类型 - 工作正常
public record RequestWithNonNestedChild(Child Child);
public record Child(string NonNullable, string? Nullable);

// 嵌套记录类型 - 出现问题
public record RequestWithNestedChild(RequestWithNestedChild.NestedChild Child)
{
    public record NestedChild(string NonNullable, string? Nullable);
}

在第一种情况下，Swagger文档会正确区分可空和不可空属性。而在嵌套定义的情况下，所有属性都会被错误地标记为可空。

解决方案

目前有以下几种应对方案：

1. 避免嵌套定义：将嵌套记录类型提取为顶级定义，这是最简单的解决方案

2. 使用Schema过滤器：实现自定义的ISchemaFilter来手动修正nullability信息

public sealed class NullableSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (schema.Properties.Count == 0)
            return;

        var nullabilityInfoContext = new NullabilityInfoContext();
        var contextProperties = context.Type.GetProperties();

        foreach (var (name, property) in schema.Properties)
        {
            var contextProperty = contextProperties.FirstOrDefault(x => 
                string.Equals(name, x.Name, StringComparison.OrdinalIgnoreCase));
            if (contextProperty is null)
                continue;

            var nullabilityInfo = nullabilityInfoContext.Create(contextProperty);
            if (nullabilityInfo.ReadState == NullabilityState.Nullable)
                property.Nullable = true;
        }
    }
}

3. 等待官方修复：该问题已被项目维护者确认，并纳入修复计划

最佳实践建议

在实际开发中，建议：

1. 对于简单的DTO，优先使用非嵌套的记录类型定义
2. 如果必须使用嵌套定义，考虑添加明确的XML注释说明非空约束
3. 在团队内部建立API契约评审流程，确保生成的文档符合预期
4. 定期更新Swashbuckle.AspNetCore版本，关注相关修复进展

这个问题虽然不会影响运行时行为，但会导致API文档不准确，可能误导API消费者。开发者应当根据项目实际情况选择合适的应对方案，确保API契约的正确性。