.NET 6 Web API中如何让Swagger显示自定义类型的完整属性

问题场景 #

我有一个名为UserLanguage的属性，类型是自定义的Language记录（包含Name、Alpha2Code和Alpha3Code三个属性）。在请求模型中使用Language类型后，Swagger仅显示：

{
  "name" : "",
  "userlanguage" : {}
}

期望显示效果：

{
      "name" : "",
      "userLanguage" : {
          "name" : "",
          "alpha2Code" : "",
          "alpha3Code" : ""
       }
 }

现有代码 #

Language 记录代码 #

public record Language
{
    public static readonly Language None = new(string.Empty, string.Empty, string.Empty);
    
    private Language(
        string alpha2Code, 
        string alpha3Code,
        string name)
    {
        Name = name;
        Alpha2Code = alpha2Code;
        Alpha3Code = alpha3Code;
    }
    public string Alpha2Code { get; private set; } = string.Empty;
    public string Alpha3Code { get; private set; } = string.Empty;
    public string? Name { get; private set; }
}

请求模型代码 #

public sealed record UserDetailsRequest(
    string Name,
    Language UserLanguage
);

解决方法 #

问题根源在于Language记录的私有构造函数和私有setter属性，Swagger的Schema生成器无法识别这类不可公开实例化类型的内部属性，可通过以下两种方式解决：

方法一：修改Language记录的访问权限（推荐） #

将构造函数改为公开，同时把属性的setter替换为init（既保持类型不可变性，又能让序列化器和Swagger识别属性）：

public record Language
{
    public static readonly Language None = new(string.Empty, string.Empty, string.Empty);
    
    // 改为公开构造函数
    public Language(
        string alpha2Code, 
        string alpha3Code,
        string name)
    {
        Name = name;
        Alpha2Code = alpha2Code;
        Alpha3Code = alpha3Code;
    }
    // 使用init替代private set，兼顾不可变性与可识别性
    public string Alpha2Code { get; init; } = string.Empty;
    public string Alpha3Code { get; init; } = string.Empty;
    public string? Name { get; init; }
}

方法二：自定义Swagger Schema过滤器（适合无法修改原类型的场景） #

如果不能调整Language的访问权限，可通过自定义过滤器手动添加属性定义：

1. 创建过滤器类：

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

public class LanguageSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(Language))
        {
            schema.Properties.Clear();
            schema.Properties.Add("name", new OpenApiSchema { Type = "string", Nullable = true });
            schema.Properties.Add("alpha2Code", new OpenApiSchema { Type = "string" });
            schema.Properties.Add("alpha3Code", new OpenApiSchema { Type = "string" });
        }
    }
}

2. 在Program.cs中注册过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.SchemaFilter<LanguageSchemaFilter>();
});

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