Swagger加载失败报Failed to load API definition undefined错误求助

这个报错的核心原因是Swagger扫描公开接口生成OpenAPI文档时遇到解析冲突或异常，将接口方法改为private会让Swagger跳过该方法的扫描，因此会临时绕过问题，可按照以下步骤定位修复：

• 开启Swagger详细错误日志，直接定位问题点
  在服务注册Swagger的代码中新增错误输出配置：

  builder.Services.AddSwaggerGen(c =>
  {
      // 保留原有配置的基础上新增以下内容
      // 开启Swagger生成过程的详细错误，会直接提示具体哪个接口/模型出问题
      c.CustomSchemaIds(type => type.FullName);
  });
  
  // 若项目使用Newtonsoft.Json做序列化，新增以下配置避免System.Text.Json的解析兼容问题
  builder.Services.AddSwaggerGenNewtonsoftSupport();
  
  // 接口序列化配置中新增循环引用处理，避免模型存在循环依赖导致解析失败
  builder.Services.AddControllers()
      .AddJsonOptions(options =>
      {
          options.JsonSerializerOptions.ReferenceHandler = System.Text.Json.Serialization.ReferenceHandler.IgnoreCycles;
      });
  

  配置后重启项目，再次打开Swagger页面，错误提示会明确显示具体是路由冲突、模型解析失败还是其他问题。

• 排查路由冲突问题
  检查两个控制器是否配置了全局路由前缀，若控制器本身加了[Route("api/[controller]")]这类前缀，方法上再写[Route("api/xxx")]会导致最终路由规则异常；如果需要使用方法级的绝对路由，可在路由前加/，比如[Route("/api/SearchLABResults")]，避免和控制器路由前缀叠加。

• 排查入参模型问题
  确认SP_GET_LABResult_Overview.input和AuthenticationModel.input两个入参类：

  • 存在公共无参构造函数
  • 内部属性没有不可序列化的类型（比如Stream、委托、非公开类型等）
  • 没有和其他类同名且命名空间不同的情况，前面配置的CustomSchemaIds用全限定名可以解决这类冲突。

• 排查控制器属性配置
  确认两个控制器都添加了[ApiController]特性，避免WebAPI的路由、模型绑定规则解析异常。

内容的提问来源于stack exchange，提问作者Yo Akarapol Imphrom