如何让Swagger正确展示Record实现的强类型Id的API定义？

问题背景 #

使用Record实现强类型Id：

[TypeConverter(typeof(ClientIdTypeConverter))]
public record ClientId(Ulid Value);

已配置好Entity Framework和Json转换器，请求对象序列化结果正常：

public class Request
{
    [TypeConverter(typeof(ClientIdTypeConverter))]
    [JsonPropertyName("ClientId")]
    public ClientId Id { get; set; }
    public string Name { get; set; }
}

序列化后输出：

{
    "ClientId": "someidstring",
    "Name": "some name"
}

但Swagger生成的API定义错误地将ClientId显示为嵌套结构，而非字符串类型。

解决方案 #

通过自定义Swagger Schema过滤器，强制将ClientId类型映射为字符串格式：

1. 实现Schema过滤器 #

创建一个实现ISchemaFilter的类，修改ClientId对应的Schema定义：

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

public class ClientIdSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(ClientId))
        {
            // 将Schema类型设为字符串，格式指定为uuid（匹配Ulid的字符串格式）
            schema.Type = "string";
            schema.Format = "uuid";
            // 清除默认生成的嵌套属性
            schema.Properties.Clear();
            schema.Reference = null;
        }
    }
}

2. 配置Swagger启用过滤器 #

在Program.cs的Swagger配置中添加该过滤器：

builder.Services.AddSwaggerGen(c =>
{
    // 注册自定义Schema过滤器
    c.SchemaFilter<ClientIdSchemaFilter>();
    
    // 其他Swagger配置（如文档标题、版本等）
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API", Version = "v1" });
});

3. 验证效果 #

配置完成后，Swagger将显示正确的API定义：

{
    "ClientId": "someidstring",
    "Name": "some name"
}

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