.NET 6中Swagger UI未显示ErrorList模型详情问题

核心原因 #

Swagger 默认仅扫描被控制器Action直接声明为返回类型、参数或通过特性标注的类型。ErrorList 仅在catch块中返回，未被Action的公开API契约明确引用，因此未被Swagger纳入扫描范围。

解决方法 #

方法1：通过特性显式标注返回类型 #

在控制器的Action上添加 ProducesResponseType 特性，明确声明该Action可能返回ErrorList类型：

[HttpGet]
[ProducesResponseType(typeof(ErrorList), StatusCodes.Status500InternalServerError)]
public IActionResult GetData()
{
    try
    {
        // 业务逻辑
        return Ok();
    }
    catch
    {
        return StatusCode(StatusCodes.Status500InternalServerError, new ErrorList());
    }
}

方法2：强制Swagger包含目标类型 #

自定义SchemaFilter，强制Swagger扫描ErrorList及其依赖的Errors类：

1. 创建SchemaFilter类：

public class IncludeErrorTypesFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 空实现，仅用于触发类型扫描
    }

    // 静态构造函数确保类型被加载
    static IncludeErrorTypesFilter()
    {
        _ = typeof(ErrorList);
        _ = typeof(Errors);
    }
}

2. 在Swagger配置中注册该过滤器：

public static void ConfigureSwaggerServices(this IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        // 原有配置...
        
        // 添加自定义过滤器
        c.SchemaFilter<IncludeErrorTypesFilter>();
    });
}

方法3：检查XML注释文件有效性 #

1. 确认Models.xml文件已正确生成（项目属性→生成→勾选"XML文档文件"），且包含ErrorList和Errors类的注释。
2. 修正XML文件路径，避免硬编码导致的环境差异：

var modelsXmlPath = Path.Combine(AppContext.BaseDirectory, "Models.xml");
c.IncludeXmlComments(modelsXmlPath);

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