.NET 6 下 Swagger 复杂请求响应示例在 Swagger UI 渲染问题咨询

1. ExamplesOperationFilter 找不到的原因 #

Swashbuckle.AspNetCore.Filters 从7.0.0版本开始，将ExamplesOperationFilter调整为内部类，不再对外暴露，老教程中手动注册OperationFilter<ExamplesOperationFilter>()的写法已经失效。
你不需要再手动寻找这个类，直接使用官方封装的扩展方法启用示例过滤器即可。

2. .NET 6 环境复杂Swagger示例配置步骤 #

2.1 基础配置（Program.cs） #

using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

// 注册服务
builder.Services.AddControllers();

// Swagger配置
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "ApiDemo", Version = "v1" });
    
    // 引入XML注释（可保留你原有配置）
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath, true);

    // 启用示例过滤器，替代旧版手动注册ExamplesOperationFilter的写法
    c.ExampleFilters();
});

// 注册当前程序集中所有实现了IExamplesProvider接口的示例类
builder.Services.AddSwaggerExamplesFromAssemblies(Assembly.GetEntryAssembly());

var app = builder.Build();

// 中间件配置
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseAuthorization();
app.MapControllers();
app.Run();

2.2 复杂结构示例编写 #

你可以通过实现IExamplesProvider<T>接口自定义任意复杂结构的示例，完全支持嵌套对象、列表、数组、枚举等类型：

示例DTO定义

// 枚举示例
public enum OrderStatus
{
    Pending,
    Paid,
    Shipped,
    Completed
}

// 嵌套子对象示例
public class OrderItemDto
{
    public long ItemId { get; set; }
    public string ItemName { get; set; }
    public int Count { get; set; }
    public decimal UnitPrice { get; set; }
}

// 主请求DTO示例
public class CreateOrderRequestDto
{
    public long UserId { get; set; }
    public string Address { get; set; }
    public List<OrderItemDto> Items { get; set; }
    public OrderStatus Status { get; set; }
    public string[] RemarkTags { get; set; }
}

对应示例类实现

using Swashbuckle.AspNetCore.Filters;

public class CreateOrderRequestExample : IExamplesProvider<CreateOrderRequestDto>
{
    public CreateOrderRequestDto GetExamples()
    {
        return new CreateOrderRequestDto
        {
            UserId = 10086,
            Address = "北京市朝阳区XX街道XX小区1号楼3单元101",
            Status = OrderStatus.Pending,
            RemarkTags = new[] { "易碎品", "工作日派送" },
            Items = new List<OrderItemDto>
            {
                new()
                {
                    ItemId = 2001,
                    ItemName = "无线蓝牙耳机",
                    Count = 1,
                    UnitPrice = 399.9m
                },
                new()
                {
                    ItemId = 2005,
                    ItemName = "Type-C充电线",
                    Count = 2,
                    UnitPrice = 19.9m
                }
            }
        };
    }
}

2.3 接口绑定示例（可选） #

如果需要手动指定接口和示例的绑定关系，或者指定不同状态码的响应示例，可以在接口上添加对应特性：

[HttpPost("create")]
[SwaggerRequestExample(typeof(CreateOrderRequestDto), typeof(CreateOrderRequestExample))]
[SwaggerResponseExample(StatusCodes.Status200OK, typeof(CreateOrderResponseExample))]
public async Task<IActionResult> CreateOrder(CreateOrderRequestDto request)
{
    // 业务逻辑实现
    return Ok();
}

以上配置在你使用的.NET 6 RC1 + Swashbuckle.AspNetCore 6.2.1 + Swashbuckle.AspNetCore.Filters 7.0.2环境下可正常运行，Swagger UI会完整渲染所有复杂结构的请求、响应示例。

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