FastEndpoints项目中实现多态类型在Swagger中的展示

在FastEndpoints项目中处理多态类型(Polymorphism)时，开发者常常会遇到如何在Swagger文档中正确展示继承类结构的问题。本文将详细介绍如何在FastEndpoints中配置多态类型的Swagger展示，包括基础配置和高级用法。

多态类型的基本配置

FastEndpoints使用NSwag作为其Swagger生成引擎，与Swashbuckle的处理方式有所不同。要实现多态类型的正确展示，首先需要在基类上添加适当的JSON序列化注解：

[
    JsonPolymorphic(TypeDiscriminatorPropertyName = "_t"),
    JsonDerivedType(typeof(Apple), "a"),
    JsonDerivedType(typeof(Orange), "o")
]
public class Fruit
{
    public string Baz { get; set; }
}

这里的关键点包括：

• JsonPolymorphic 指定类型鉴别器属性名
• JsonDerivedType 定义每个派生类及其对应的鉴别器值

启用OneOf展示模式

从FastEndpoints v5.28版本开始，开发者可以启用更直观的OneOf展示模式：

.SwaggerDocument(c => c.UseOneOfForPolymorphism = true)

启用此功能后，Swagger文档会以更清晰的方式展示多态类型结构，明确列出所有可能的派生类型。

实际效果展示

配置完成后，Swagger UI将显示以下结构：

1. 基类定义中包含所有公共属性
2. 派生类通过OneOf结构明确列出
3. 类型鉴别器字段(_t)作为必需属性显示
4. 示例JSON中自动包含正确的鉴别器值

常见问题解决

1. 鉴别器字段缺失问题：确保在基类上正确设置了TypeDiscriminatorPropertyName
2. 派生类未显示：检查所有派生类是否都通过JsonDerivedType注册
3. Swagger UI显示不完整：升级到最新版本FastEndpoints以获取完整功能支持

最佳实践建议

1. 为类型鉴别器使用统一的属性名(如_t)
2. 为每个派生类定义简洁明了的鉴别器值
3. 在API文档中补充说明多态类型的使用方式
4. 考虑为客户端开发者提供类型映射表参考

通过以上配置，开发者可以在FastEndpoints项目中实现清晰、准确的多态类型Swagger文档展示，极大提升API的可理解性和易用性。