如何让NSwag生成的Swagger文档展示discriminator鉴别器字段

问题描述 #

我们开发了API服务，使用NSwag工具自动生成Swagger接口文档。服务内部分接口借助继承机制实现字段更新逻辑：以POST api/person/{id}接口为例，用户在请求体提交JSON时，需传入discriminator字段，程序才能识别具体类型，完成JSON反序列化后调用对应更新方法（如UpdateAddress等）；若用户未传入该字段，客户端反序列化得到的对象会为null，最终引发错误。

当前已通过如下配置让文档正确可视化继承结构及对应属性：

[JsonConverter(typeof(JsonInheritanceConverter), "discriminator")]
[KnownType(typeof(PersonUpdateAddressCommand))]
public class PersonCommand : CommandBase
{
} 

但生成的Swagger文档默认不会展示discriminator属性，用户无法从文档得知需要传入该字段，不符合接口文档自解释的要求。

临时解决方案是在CommandBase基类中额外添加同名公共属性：

public abstract class CommandBase
{
  public string discriminator { get; set; }
}

该方案虽然能让文档展示字段，但存在冗余：discriminator字段本身已在序列化处理逻辑中存在，无需额外定义对应属性。

核心疑问：是否存在无需额外定义属性，即可让NSwag生成的Swagger文档展示discriminator字段的方案？额外定义字符串属性是否为标准实现方式？

解决方案 #

手动在基类添加discriminator属性属于冗余的临时变通方案，不是标准实现。NSwag原生支持自动识别继承转换器配置的鉴别器字段，自动注入到Swagger模型中，无需手动定义属性，配置方式如下：

• 打开NSwag生成配置：如果是ASP.NET Core项目，找到AddOpenApiDocument/AddSwaggerDocument的服务注册代码；如果是使用NSwag Studio，找到Schema Settings配置面板。
• 将GenerateDiscriminatorProperty配置项设置为true。
• 确认DiscriminatorName配置项的值和你在JsonInheritanceConverter构造函数中传入的鉴别器字段名一致，这里应为discriminator。

ASP.NET Core项目配置示例：

services.AddOpenApiDocument(config =>
{
    // 保留原有其他配置
    config.SchemaSettings.GenerateDiscriminatorProperty = true;
    config.SchemaSettings.DiscriminatorName = "discriminator";
});

配置生效后，NSwag会自动完成以下处理：

• 为所有标记了JsonInheritanceConverter的基类模型自动添加discriminator字段
• 自动将该字段标记为必填项
• 自动枚举所有派生类对应的鉴别器值，作为字段的可选提示
• 不会干扰原有序列化/反序列化逻辑

注意事项 #

• 如果项目使用System.Text.Json而非Newtonsoft.Json，请将NSwag版本升级到13.10.0及以上，低版本对System.Text.Json场景下的鉴别器识别存在已知bug。
• 配置生效后请删除之前手动在基类添加的discriminator属性，避免Swagger文档中出现重复字段。

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