如何在C# API Controller中实现Swagger oneOf特性？

针对Swashbuckle.AspNetCore.Newtonsoft 6.5.0版本，要生成包含oneOf的Swagger Schema，不能直接用dynamic或普通接口，需要结合基类+子类，并通过JsonSubtypes特性让Swagger识别多态类型。以下是完整示例：

1. 安装依赖包 #

确保已安装以下NuGet包：

• Swashbuckle.AspNetCore.Newtonsoft 6.5.0
• JsonSubtypes（用于处理JSON序列化的多态映射）

2. 定义多态实体类 #

using JsonSubtypes;
using Newtonsoft.Json;

[JsonConverter(typeof(JsonSubtypes), "AnimalType")]
[JsonSubtypes.KnownSubType(typeof(Cat), "Cat")]
[JsonSubtypes.KnownSubType(typeof(Dog), "Dog")]
[JsonSubtypes.KnownSubType(typeof(Hamster), "Hamster")]
public abstract class Animal
{
    public string AnimalType { get; set; }
    public string Name { get; set; }
}

public class Cat : Animal
{
    public int LivesRemaining { get; set; }
}

public class Dog : Animal
{
    public string FavoriteToy { get; set; }
}

public class Hamster : Animal
{
    public int WheelSpeed { get; set; }
}

• AnimalType字段作为类型判别符，Swagger会通过它识别具体子类
• [JsonConverter]和[KnownSubType]特性告诉JSON序列化器和Swagger如何映射子类

3. 编写API Controller #

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class AnimalsController : ControllerBase
{
    [HttpPost]
    public IActionResult AddAnimal([FromBody] Animal animal)
    {
        // 根据AnimalType处理不同类型的动物逻辑
        return Ok($"Received {animal.AnimalType}: {animal.Name}");
    }
}

直接用基类Animal作为请求体参数，Swagger会自动生成oneOf的Schema引用

4. 配置Swagger服务 #

在Program.cs（或Startup.cs）中配置Swagger，启用Newtonsoft支持并集成JsonSubtypes：

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

var builder = WebApplication.CreateBuilder(args);

// 添加控制器服务
builder.Services.AddControllers()
    .AddNewtonsoftJson(); // 启用Newtonsoft JSON序列化

// 配置Swagger
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Animal API", Version = "v1" });
    // 启用Newtonsoft支持，确保Swagger识别JsonSubtypes的多态配置
    c.UseAllOfForInheritance();
    c.SelectSubTypesUsing(baseType => baseType.Assembly.GetTypes().Where(t => baseType.IsAssignableFrom(t)));
});

var app = builder.Build();

// 启用Swagger中间件
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

• UseAllOfForInheritance()：让Swagger用allOf处理继承关系，配合oneOf实现多态请求体
• SelectSubTypesUsing：确保Swagger能扫描到所有子类

最终Swagger效果 #

生成的Swagger请求体Schema会显示oneOf引用Cat、Dog、Hamster三个类型，并且会自动识别AnimalType作为判别字段，请求时只需传入对应类型的JSON即可。

内容的提问来源于stack exchange，提问作者Sergio Dalla Valle