如何使用Swashbuckle在Swagger中为object[]的多对象类型生成文档

实现结论 #

该需求完全可以实现，不需要修改外部服务商提供的模型代码，仅通过Swashbuckle的扩展能力就可以自定义Swagger文档的展示内容。

推荐实现方式：自定义Schema过滤器 #

Schema过滤器是Swashbuckle提供的原生扩展能力，可在Swagger文档生成阶段修改指定模型的字段描述、示例、允许类型等配置，完全适配你的场景。

步骤1：实现自定义Schema过滤器 #

using Swashbuckle.AspNetCore.SwaggerGen;
using Microsoft.OpenApi.Models;
using System.Linq;
using System.Collections.Generic;

// 替换代码中所有占位的类型、字段名为你项目实际的对应名称
public class CustomArraySchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 匹配外部服务商提供的包含object[]字段的模型类型
        if (context.Type == typeof(你项目中外部模型的类名))
        {
            // 匹配目标object[]类型字段，替换为实际字段名
            var targetArrayProp = schema.Properties.FirstOrDefault(p => p.Key == "MyObject");
            if (targetArrayProp.Value != null)
            {
                // 补充字段说明，告知使用者可传入的对象类型
                targetArrayProp.Value.Description = "数组项支持传入Object1或Object2两种类型的对象，结构参考示例：";
                // 替换默认的null示例为两种对象的实际示例
                targetArrayProp.Value.Example = new OpenApiArray
                {
                    // Object1示例
                    new OpenApiObject
                    {
                        ["Field1"] = new OpenApiString("Object1字段1示例值"),
                        ["Field2"] = new OpenApiString("Object1字段2示例值")
                    },
                    // Object2示例
                    new OpenApiObject
                    {
                        ["Field1"] = new OpenApiString("Object2字段1示例值"),
                        ["Field2"] = new OpenApiString("Object2字段2示例值")
                    }
                };
                // 可选配置：明确标注数组项允许的两种类型，Swagger会自动关联两种类型的定义
                targetArrayProp.Value.Items.AnyOf = new List<OpenApiSchema>
                {
                    context.SchemaGenerator.GenerateSchema(typeof(Object1), context.SchemaRepository),
                    context.SchemaGenerator.GenerateSchema(typeof(Object2), context.SchemaRepository)
                };
            }
        }
    }
}

步骤2：注册过滤器到Swagger配置 #

在Startup.cs的ConfigureServices方法中，找到Swagger注册逻辑，添加过滤器注册：

services.AddSwaggerGen(options =>
{
    // 保留你原有的Swagger配置，比如SwaggerDoc、XML注释加载等
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API文档", Version = "v1" });
    // 注册自定义的Schema过滤器
    options.SchemaFilter<CustomArraySchemaFilter>();
});

效果说明 #

配置完成后重新启动项目，Swagger文档中对应的MyObject数组字段会替换原来的null占位，直接展示你设置的两种对象示例，同时会显示补充的字段说明，使用者可以清晰了解该字段的传入规则。

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