Swagger UI无法展开嵌套字段问题咨询（基于Swashbuckle）

这种不一致的行为不属于预期情况，是Swashbuckle/Swagger-UI在嵌套模型渲染上的常见bug或配置问题，不少开发者都遇到过，以下是验证过的解决思路：

• 升级Swashbuckle版本：旧版本（比如v5.x及更早）存在嵌套Schema渲染的逻辑缺陷，升级到最新稳定版（如Swashbuckle.AspNetCore v6.x+），官方修复了大量嵌套模型的展示问题，很多情况下直接升级就能解决。

• 调整Swagger-UI的渲染配置：在启动配置里修改默认的模型展开深度和渲染方式，强制让单独的Schema也能展开嵌套结构：

  app.UseSwaggerUI(c =>
  {
      c.DefaultModelExpandDepth(3); // 设置足够大的展开深度，覆盖默认的浅层次展开
      c.DefaultModelRendering(ModelRendering.Model); // 强制以模型形式渲染，而非只显示描述
  });
  

• 修正Schema的引用处理：如果Swashbuckle对Schema A的嵌套模型使用了引用（$ref），单独展示时可能无法正确解析引用内容。可以通过SchemaFilter取消引用，直接渲染完整嵌套结构（注意：这会导致Schema重复，适合嵌套层级不深的场景）：

  public class FlattenNestedSchemaFilter : ISchemaFilter
  {
      public void Apply(OpenApiSchema schema, SchemaFilterContext context)
      {
          if (schema.Properties == null) return;
          
          foreach (var prop in schema.Properties.Values)
          {
              // 当属性是引用类型时，替换为实际的Schema结构
              if (prop.Reference != null)
              {
                  var referencedSchema = context.SchemaGenerator.GenerateSchema(
                      context.Type.GetProperty(prop.Reference.Id)?.PropertyType, 
                      context.SchemaRepository);
                  prop.Reference = null;
                  foreach (var key in referencedSchema.Properties.Keys)
                  {
                      prop.Properties[key] = referencedSchema.Properties[key];
                  }
              }
          }
      }
  }
  
  // 在AddSwaggerGen中注册过滤器
  services.AddSwaggerGen(c =>
  {
      c.SchemaFilter<FlattenNestedSchemaFilter>();
  });
  

• 检查模型的可访问性与注解：确保Schema A及其所有嵌套模型都是公开类（public），没有被标记[ApiExplorerSettings(IgnoreApi = true)]或其他会阻止Swashbuckle扫描的注解。如果嵌套模型是内部类，单独展示时会无法解析字段，但被其他Schema引用时可能因为上下文扫描到而正常显示。

• 清理项目缓存：有时候bin/obj目录下的缓存文件会导致Swagger文档生成异常，清理后重新生成解决方案，能解决一些偶发的渲染不一致问题。

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