如何使用OpenAPI 3.0为未知类型生成Swagger文档（ASP.NET Core场景）

针对你遇到的ProductResponse中data属性实际为不确定结构JSON对象字符串的情况，可以通过以下几种方式在OpenAPI 3.0中正确生成Swagger文档：

方法一：自定义SchemaFilter（推荐，不改动业务模型） #

通过Swagger的SchemaFilter直接修改属性的OpenAPI描述，无需调整原有模型代码：

1. 创建SchemaFilter类：

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

public class ProductResponseSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type != typeof(ProductResponse)) return;
        
        if (schema.Properties.TryGetValue("data", out var dataSchema))
        {
            // 将数组元素从string类型改为任意结构的JSON对象
            dataSchema.Items = new OpenApiSchema
            {
                Type = "object",
                AdditionalProperties = true, // 允许任意键值对
                Description = "不确定结构的JSON对象"
            };
        }
    }
}

2. 在Program.cs中注册Filter：

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

方法二：修改模型类型并配合Json转换器 #

将IEnumerable<string>改为IEnumerable<object>，并通过自定义JsonConverter处理字符串与JSON对象的转换：

1. 更新ProductResponse模型：

using System.Text.Json;
using System.Text.Json.Serialization;

public class ProductResponse
{
    [JsonPropertyName("data")]
    [JsonConverter(typeof(StringToObjectConverter))]
    public IEnumerable<object> data { get; set; } = Enumerable.Empty<object>();
}

// 自定义转换器，实现JSON字符串与object的互转
public class StringToObjectConverter : JsonConverter<object>
{
    public override object Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        if (reader.TokenType == JsonTokenType.String)
        {
            var jsonStr = reader.GetString();
            return JsonSerializer.Deserialize<object>(jsonStr, options);
        }
        return JsonSerializer.Deserialize<object>(ref reader, options);
    }

    public override void Write(Utf8JsonWriter writer, object value, JsonSerializerOptions options)
    {
        // 根据业务需求选择：如果需要输出JSON字符串则保留下面代码，否则直接序列化object
        var jsonStr = JsonSerializer.Serialize(value, options);
        writer.WriteStringValue(jsonStr);
        // 若直接输出JSON对象，替换为：JsonSerializer.Serialize(writer, value, options);
    }
}

这种方式会让Swagger自动将data的元素识别为任意结构的对象，但需要调整模型类型并处理序列化逻辑。

方法三：使用Swagger注释属性 #

通过Swashbuckle.AspNetCore.Annotations包提供的属性直接指定Schema：

1. 安装依赖包：

Install-Package Swashbuckle.AspNetCore.Annotations

2. 更新模型属性：

using Swashbuckle.AspNetCore.Annotations;

public class ProductResponse
{
    [JsonPropertyName("data")]
    [SwaggerSchema(
        Items = new OpenApiSchema 
        { 
            Type = "object", 
            AdditionalProperties = true,
            Description = "不确定结构的JSON对象"
        }
    )]
    public IEnumerable<string> data { get; set; } = Enumerable.Empty<string>();
}

3. 在Program.cs中启用注释：

builder.Services.AddSwaggerGen(c =>
{
    c.EnableAnnotations();
    // 其他配置
});

以上三种方法都可以让Swagger文档正确展示data属性为包含任意结构JSON对象的数组，根据你的业务场景选择即可。

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