如何使用 Swagger UI 在 ASP.NET Core Web API 中实现多态请求体？

Question

我正在开发一个 ASP.NET Core Web API，我需要允许客户端在发送

PUT

请求时在多个派生类型之间进行选择。

我已经使用基类和派生类在代码中设置了多态性，并且我使用自定义

JsonConverter

来处理序列化。但是，Swagger UI 仅显示发送“第一”类型正文的选项，我需要启用一项功能，允许用户选择他们想要发送的特定类型。

这是我定义模型和控制器的方式：

// Base class and derived classes
public abstract class Base
{
    public Type Type { get; set; }
}

public enum Type
{
    First,
    Second
}

[JsonConverter(typeof(FirstConverter))]
public class First : Base
{
    public string Value { get; set; }
}

[JsonConverter(typeof(SecondConverter))]
public class Second : Base
{
    public string Data { get; set; }
}

// TestController
[Route("api/[controller]")]
[ApiController]
public class TestController : ControllerBase
{
    [HttpPut("/base")]
    public IActionResult First([FromBody] Base parameters)
    {
        return Ok(parameters);
    }
}

// Custom JsonConverter for polymorphism
public class TestJsonConverter : JsonConverter<Base>
{
    // Custom converter logic
}

// Swagger Configuration in Startup.cs or Program.cs
builder.Services.AddSwaggerGen(options =>
{
    options.UseOneOfForPolymorphism();
    options.UseAllOfForInheritance();
    options.SchemaFilter<NotificationSettingsSchemaFilter>();
});

但是在 Swagger UI 中，看起来我附加到了帖子中：

如您所见，UI 没有提供在请求正文的“第一”或“第二”类型之间进行选择的选项。为了启用此功能，我的 Swagger 设置中缺少什么？如何修改 Swagger 配置以允许用户在 UI 的 PUT 请求正文中的不同类型之间进行选择？

任何帮助或指示将不胜感激！

Answer 1

您想要做的事情可以使用鉴别器来实现，这些鉴别器记录在此处：https://github.com/domaindrivendev/Swashbuckle.AspNetCore#enrich-polymorphic-base-classes-with-discriminator-metadata.

应用于您的解决方案：

[SwaggerDiscriminator("type")]
[SwaggerSubType(typeof(First), DiscriminatorValue = "first")]
[SwaggerSubType(typeof(Second), DiscriminatorValue = "second")]
public abstract class Base
{
    public Type Type { get; set; }
}

这将导致从您的代码生成的 OpenAPI 规范使用 oneOf 指令和 discriminator 属性，按照以下参考：https://swagger.io/docs/specification/data-models/inheritance-and -多态性。

但是，我非常强烈敦促您考虑通过 API 公开简单的模型，而不是那些表现出多态性的模型。支持多态性很复杂，通常是不必要的，更糟糕的是，许多消费者端代码生成器很难正确处理 OpenAPI 规范中的 oneOf 和 discriminator 关键字。