.NET OpenAPI如何识别动态类型属性的多返回自定义类？

核心原因 #

你的MyClass中someObject是object类型，Swagger无法自动推断它实际可能返回的CustomClass1和CustomClass2，因此无法生成对应的模型定义，只能显示为空对象{}。

解决方案 #

方法一：使用多态基类+KnownType特性（推荐） #

通过定义共同基类并标记已知类型，让Swagger自动识别多态结构：

1. 创建基类并标记已知子类：

[KnownType(typeof(CustomClass1))]
[KnownType(typeof(CustomClass2))]
public abstract class CustomBase { }

public class CustomClass1 : CustomBase
{
    // 你的类成员
}

public class CustomClass2 : CustomBase
{
    // 你的类成员
}

2. 修改MyClass的属性类型为基类：

public class MyClass
{
    public CustomBase someObject { get; set; }

    public MyClass(CustomBase someObject)
    {
        this.someObject = someObject;
    }
}

这样Swagger会自动识别CustomBase的所有已知子类，将CustomClass1和CustomClass2加入模型定义，同时someObject会显示为可返回两种类型的结构。

方法二：使用Swagger注解直接指定多态类型 #

如果不想修改类继承结构，可以通过Swagger注解直接声明属性的可能类型：

1. 确保安装Swashbuckle.AspNetCore.SwaggerAnnotations包：

Install-Package Swashbuckle.AspNetCore.SwaggerAnnotations

2. 在MyClass的属性上添加注解：

using Swashbuckle.AspNetCore.Annotations;

public class MyClass
{
    [SwaggerSchema(OneOf = new[] { typeof(CustomClass1), typeof(CustomClass2) })]
    public object someObject { get; set; }

    public MyClass(object someObject)
    {
        this.someObject = someObject;
    }
}

3. 在Swagger配置中启用注解支持：

builder.Services.AddSwaggerGen(c =>
{
    c.EnableAnnotations();
    // 其他Swagger配置
});

此方法会让Swagger将someObject标记为可返回CustomClass1或CustomClass2，并自动将这两个类加入模型列表。

方法三：手动添加模型到Swagger文档 #

如果上述方法无法生效，可以通过文档过滤器手动注入模型定义：

1. 实现IDocumentFilter：

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

public class AddCustomModelsFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 生成CustomClass1和CustomClass2的Schema
        var custom1Schema = context.SchemaGenerator.GenerateSchema(typeof(CustomClass1), context.SchemaRepository);
        var custom2Schema = context.SchemaGenerator.GenerateSchema(typeof(CustomClass2), context.SchemaRepository);
        
        // 添加到Swagger组件的模型中
        swaggerDoc.Components.Schemas["CustomClass1"] = custom1Schema;
        swaggerDoc.Components.Schemas["CustomClass2"] = custom2Schema;
        
        // 修改MyClass的someObject属性为OneOf类型
        if (swaggerDoc.Components.Schemas.TryGetValue("MyClass", out var myClassSchema))
        {
            if (myClassSchema.Properties.TryGetValue("someObject", out var propSchema))
            {
                propSchema.OneOf = new List<OpenApiSchema>
                {
                    new() { Reference = new OpenApiReference { Type = ReferenceType.Schema, Id = "CustomClass1" } },
                    new() { Reference = new OpenApiReference { Type = ReferenceType.Schema, Id = "CustomClass2" } }
                };
                propSchema.Reference = null;
            }
        }
    }
}

2. 在Swagger配置中注册过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.DocumentFilter<AddCustomModelsFilter>();
    // 其他Swagger配置
});

替代方案 #

如果业务允许，可以直接拆分返回逻辑：

• 移除MyClass包装，根据条件直接返回CustomClass1或CustomClass2，并在API方法上添加多个ProducesResponseType：

[HttpGet()]
[Produces("application/json")]
[ProducesResponseType(typeof(CustomClass1), 200)]
[ProducesResponseType(typeof(CustomClass2), 200)]
public async Task<IActionResult> ApiMethod([Required] string input)
{
    if (...)
        return Ok(new CustomClass1());
    else
        return Ok(new CustomClass2());
}

这种方式更符合RESTful设计，Swagger也能自动识别两种返回模型。

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