.NET使用Swashbuckle时Swagger UI未显示已引用自定义查询模型的问题

针对你编写的userQuery模型未在Swagger UI模型列表展示的问题，通常是以下几处配置或代码细节遗漏导致的，按优先级逐一排查即可解决：

• 第一优先级：核对类型引用的匹配准确性
  你当前控制器代码中写的参数类型是userQuery（首字母小写），但实际定义的模型类是UserQuery（首字母大写，符合C#公共类的命名规范）。虽然C#编译器对类名的大小写引用存在一定容错，但Swashbuckle 在做类型扫描时，会严格匹配类型的完整命名空间与类名，如果因为拼写偏差、大小写不匹配，导致参数实际绑定的并非Project.Models下你定义的那个UserQuery类，自然不会被提取到Swagger的模型列表中。
  你需要把参数类型修正为和类定义完全一致的名称，确认using Project.Models;的引用没有遗漏、没有出现同名类冲突的情况。
• 第二优先级：检查Swagger的程序集扫描范围
  默认Swashbuckle 只会扫描启动程序集下的公开类型，如果你的模型类定义在独立的类库项目中，没有被纳入Swagger的扫描范围，就会出现“控制器引用了类但模型不显示”的问题。
  需要在Swagger服务注册的配置中，手动补充对应程序集的类型扫描，示例配置参考：

  services.AddSwaggerGen(options =>
  {
      // 保留原有的Swagger基础配置
      options.SwaggerDoc("v1", new OpenApiInfo { Title = "Project API", Version = "v1" });
      // 将模型类所在项目的XML注释纳入扫描范围
      options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "Project.Models.xml"));
  });
  

• 第三优先级：排查自定义过滤规则的拦截
  如果之前在Swagger配置中自定义了DocInclusionPredicate、自定义SchemaFilter等逻辑，有可能把不满足规则的模型类排除在生成列表外。比如部分自定义过滤规则只会把接口直接返回值的类型加入模型列表，不会把请求参数绑定的复杂类型纳入，这时候需要调整过滤规则，确保UserQuery这类请求参数类型不被拦截。
• 细节排查项：
  确认UserQuery类本身没有被标注[ApiExplorerSettings(IgnoreApi = true)]这类强制忽略的特性，否则无论怎么引用都不会在Swagger UI中显示。

修正后的接口写法参考：

[HttpGet]
[Authorize(Policy = "Read-Run")]
[Route("byRoute/{element}")]        
[Produces(typeof(EntityResult<EntityResponse>))]
public async Task<IActionResult> ListEntities([FromQuery] UserQuery entityMatch, [FromRoute] string element)
{
    return Ok(await _entityService.ListEntities(entityMatch, element));
}

完成上述排查后，正常情况下UserQuery类就会自动出现在Swagger UI底部的模型列表中。

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