如何在Swagger UI显示对象字符串同时将完整对象存入Cosmos DB

问题根源 #

你当前在Dependency类的Range属性上直接标记了[JsonConverter(typeof(RangeConverter))]，这个特性会全局作用于所有序列化/反序列化场景：

• Swagger UI生成文档时，会用转换器把Range转成字符串（符合预期）
• 但将对象序列化存入Cosmos DB时，同样会调用这个转换器，只输出Range的字符串表示，丢失了IsFloating等属性

解决方案：拆分Swagger显示与存储序列化逻辑 #

核心思路是：让Swagger单独处理Range的显示为字符串，而实际的对象序列化（存Cosmos）使用默认逻辑，保留完整Range属性。

方案一：使用Swagger Schema过滤器（推荐） #

通过Swagger的ISchemaFilter修改Range类型在文档中的显示，不影响实际的序列化/反序列化流程。

1. 移除属性上的JsonConverter特性

修改Dependency类，去掉[JsonConverter]标记：

public class Dependency
{        
    public string Name { get; set; }
   
    [JsonProperty("Range")]        
    // 移除这一行：[JsonConverter(typeof(RangeConverter))]
    public Range Range { get; set; }
}

2. 实现Swagger Schema过滤器

创建过滤器，将Range类型在Swagger文档中显示为字符串，并设置示例值：

public class RangeSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 处理单个Range类型
        if (context.Type == typeof(Range))
        {
            schema.Type = "string";
            schema.Format = null;
            schema.Example = new OpenApiString(VersionRange.Parse("[1,2)").ToString());
        }
        // 处理Dependency类中的Range属性
        else if (context.Type == typeof(Dependency))
        {
            if (schema.Properties.TryGetValue("Range", out var rangeSchema))
            {
                rangeSchema.Type = "string";
                rangeSchema.Format = null;
                rangeSchema.Example = new OpenApiString(VersionRange.Parse("[1,2)").ToString());
            }
        }
        // 处理包含Dependency的列表类型
        else if (context.Type.IsGenericType 
                 && context.Type.GetGenericTypeDefinition() == typeof(List<>) 
                 && context.Type.GetGenericArguments()[0] == typeof(Dependency))
        {
            if (schema.Items?.Properties.TryGetValue("Range", out var rangeSchema) == true)
            {
                rangeSchema.Type = "string";
                rangeSchema.Format = null;
                rangeSchema.Example = new OpenApiString(VersionRange.Parse("[1,2)").ToString());
            }
        }
    }
}

3. 注册Swagger过滤器

在Program/Startup中添加过滤器到Swagger配置：

builder.Services.AddSwaggerGen(c =>
{
    c.SchemaFilter<RangeSchemaFilter>();
    // 其他Swagger配置（如文档标题、版本等）
});

4. 完善RangeConverter的反序列化逻辑

确保客户端传入的字符串能正确解析为完整Range对象：

public class RangeConverter : JsonConverter<Range>
{
    public override void WriteJson(JsonWriter writer, Range value, JsonSerializer serializer)
    {
        // 这个方法现在只会在手动指定转换器时触发，Swagger不再依赖它
        writer.WriteValue(value.ToString());
    }
   
    public override Range ReadJson(JsonReader reader, Type objectType, Range existingValue, bool hasExistingValue, JsonSerializer serializer)
    {
        if (reader.Value is string rangeStr)
        {
            // 替换为你实际的Range字符串解析逻辑
            return VersionRange.Parse(rangeStr);
        }
        // 兼容极端情况：如果传入的是完整对象，用默认反序列化
        return serializer.Deserialize<Range>(reader);
    }
}

方案二：存储Cosmos时跳过转换器（备选） #

如果必须保留属性上的[JsonConverter]，可以在存储Cosmos时，使用不包含该转换器的序列化配置：

// 存储到Cosmos时，创建自定义序列化设置
var cosmosSerializerSettings = new JsonSerializerSettings();
// 移除RangeConverter
cosmosSerializerSettings.Converters.RemoveAll(c => c is RangeConverter);

// 序列化对象为完整JSON（包含Range的所有属性）
var fullJson = JsonConvert.SerializeObject(yourDto, cosmosSerializerSettings);

// 将fullJson存入Cosmos DB

效果验证 #

• Swagger UI中，Range属性会显示为字符串类型，示例值为[1.0.0, 2.0.0)
• 客户端提交字符串格式的Range后，会被反序列化为完整的Range对象
• 存入Cosmos DB时，对象会被序列化为包含IsFloating等所有属性的JSON

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