.NET 9 OpenAPI项目中Car继承类未在NSwagStudio生成代码问题

核心原因 #

ASP.NET Core默认的Swagger/OpenAPI生成器不会自动扫描抽象类的子类，需要显式配置多态映射才能让文档包含子类定义。

具体解决方案 #

1. 使用[KnownType]标记抽象类 #

在抽象类Vehicle上添加KnownType特性，指定它的子类Car，这是最直接的方式，兼容数据契约的同时被OpenAPI生成器识别：

[KnownType(typeof(Car))]
public abstract class Vehicle
{
    public string Id { get; set; }
    public string Model { get; set; }
}

public class Car : Vehicle
{
    public int NumberOfDoors { get; set; }
}

2. 配置Swagger生成器的多态支持 #

在Program.cs的AddSwaggerGen配置中，显式指定抽象类的子类，或者扫描程序集自动发现子类：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });

    // 方式1：手动指定抽象类的子类
    c.SelectSubTypesUsing(baseType =>
    {
        return baseType == typeof(Vehicle) 
            ? new[] { typeof(Car) } 
            : Enumerable.Empty<Type>();
    });

    // 方式2：自动扫描程序集中所有抽象类的非抽象子类（更通用）
    // c.SelectSubTypesUsing(baseType =>
    // {
    //     return AppDomain.CurrentDomain.GetAssemblies()
    //         .SelectMany(assembly => assembly.GetTypes())
    //         .Where(type => type.IsSubclassOf(baseType) && !type.IsAbstract);
    // });
});

3. 配置System.Text.Json的多态序列化 #

如果API使用System.Text.Json处理序列化，需要在Json配置中添加多态映射，确保序列化/反序列化正常的同时，让OpenAPI生成器读取到类型信息：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default);
    });

// 生成Json序列化上下文，配置多态
[JsonSerializable(typeof(Vehicle))]
[JsonSerializable(typeof(Car))]
[JsonSourceGenerationOptions(
    PolymorphismOptions = new JsonPolymorphismOptions
    {
        TypeDiscriminatorPropertyName = "$type", // 类型识别字段名
        DerivedTypes = { new JsonDerivedType(typeof(Car), nameof(Car)) }
    })]
public partial class AppJsonSerializerContext : JsonSerializerContext
{
}

4. 确保API方法中实际使用子类实例 #

在你的接口方法中，确保有返回或接收Car实例的场景，帮助生成器检测到子类的存在：

[HttpPost("request-vehicle")]
public IActionResult RequestVehicle([FromBody] RequestVehicle request)
{
    // 返回Car实例，让生成器识别到子类
    var car = new Car { Id = "CAR-001", Model = "Model 3", NumberOfDoors = 4 };
    return Ok(car);
}

public class RequestVehicle
{
    public Vehicle Vehicle { get; set; }
}

验证方法 #

启动项目后访问/openapi/v1.json，检查Vehicle的schema是否包含oneOf字段并引用Car的schema。确认后，用该JSON在NSwagStudio生成客户端代码，就能看到Car类被正确生成。

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