在Swagger中显示Minimal Web API的子类型Schema求助

问题根源是Swagger默认不会自动识别接口的实现类作为可接受的请求参数子类型，需显式配置多态支持，按以下步骤处理：

1. 配置Swagger的多态Schema生成 #

在Program.cs中添加OpenAPI配置，启用多态支持并指定已知子类型：

builder.Services.AddOpenApi(options =>
{
    // 添加接口的实现类到已知类型列表
    options.SchemaGeneratorOptions.KnownTypes.Add(typeof(SubTypeA));
    options.SchemaGeneratorOptions.KnownTypes.Add(typeof(SubTypeB));
    
    // 使用OneOf语法展示多态类型
    options.SchemaGeneratorOptions.UseOneOfForPolymorphism = true;
    // 启用鉴别器字段，用于区分不同子类型
    options.SchemaGeneratorOptions.UseDiscriminatorForPolymorphism = true;
});

也可以通过给BaseType接口添加[KnownType]特性来指定子类型，替代上述KnownTypes.Add配置：

using System.Runtime.Serialization;

[KnownType(typeof(SubTypeA))]
[KnownType(typeof(SubTypeB))]
public interface BaseType
{ 
    public int p1 { get; set; } 
}

2. 配置JSON反序列化的多态支持 #

接口无法直接实例化，需告诉System.Text.Json如何根据请求中的鉴别器字段解析到对应子类型，添加以下配置：

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(0, new PolymorphicTypeResolver());
});

// 自定义多态类型解析器
public class PolymorphicTypeResolver : DefaultJsonTypeInfoResolver
{
    public PolymorphicTypeResolver()
    {
        Modifiers.Add(typeInfo =>
        {
            if (typeInfo.Type == typeof(BaseType))
            {
                typeInfo.PolymorphismOptions = new JsonPolymorphismOptions
                {
                    // 指定鉴别器字段名，默认是$type
                    TypeDiscriminatorPropertyName = "$type",
                    // 忽略未识别的鉴别器值
                    IgnoreUnrecognizedTypeDiscriminators = true,
                    // 映射子类型和对应的鉴别器值
                    DerivedTypes =
                    {
                        new JsonDerivedType(typeof(SubTypeA), nameof(SubTypeA)),
                        new JsonDerivedType(typeof(SubTypeB), nameof(SubTypeB))
                    }
                };
            }
        });
    }
}

3. 验证效果 #

启动项目后，Swagger文档的/search接口请求体Schema会显示为OneOf类型，包含SubTypeA和SubTypeB的完整字段定义。客户端请求时需在JSON中携带鉴别器字段，示例：

{
  "$type": "SubTypeA",
  "p1": 456
}

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