SwaggerDocument创建失败，API定义加载异常排查求助

先梳理下你的项目结构：

• 控制台应用：负责启动WebAPI启动项目（DLL）
• WebAPI启动项目（DLL）：仅包含配置逻辑（容器、授权、通过AssemblyPart初始化控制器）
• 控制器类库（DLL）：包含具体的API方法实现

你当前的Swagger配置代码如下：

ConfigureService 中的Swagger配置 #

services.AddSwaggerGen(options => {
    options.DescribeAllEnumsAsStrings();
    options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info {
        Title = "TestAPI",
        Version = "v1",
        Description = "TestApplication API for modular monolith .NET application.",
    });
    var baseDirectory = AppDomain.CurrentDomain.BaseDirectory;
    var commentsFileName = "Test.Modules.UserAccess.Facade.XML";//Assembly.GetExecutingAssembly().GetName().Name + ".XML";
    var commentsFile = Path.Combine(baseDirectory, commentsFileName);
    options.IncludeXmlComments(commentsFile);
    var securityToken = new Dictionary<string, IEnumerable<string>> { {"Bearer", new string[] { }}, };
    options.AddSecurityDefinition("Bearer", new ApiKeyScheme {
        Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
        Name = "Authorization",
        In = "header",
        Type = "apiKey"
    });
    options.AddSecurityRequirement(securityToken);
});

Configure 中的Swagger配置 #

public void Configure(IApplicationBuilder app, IHostingEnvironment env, IServiceProvider serviceProvider) {
    app.UseSwagger();
    app.UseSwaggerUI(c => {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "TestAPI");
        c.RoutePrefix = string.Empty;
    });
}

结合你的模块化项目结构和问题描述，我整理了几个排查方向：

1. 验证XML注释文件的路径与合法性 #

你当前硬编码了XML文件名，这在模块化项目里很容易出错：

• 替换硬编码的文件名，改用程序集动态获取，避免拼写错误：

  // 加载控制器类库的程序集
  var controllerAssembly = Assembly.Load("Test.Modules.UserAccess.Facade");
  var commentsFileName = controllerAssembly.GetName().Name + ".XML";
  var commentsFile = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, commentsFileName);
  

• 输出路径到调试日志，确认文件存在：

  System.Diagnostics.Debug.WriteLine($"XML注释文件路径：{commentsFile}");
  

• 直接打开XML文件检查格式：如果文件存在但有语法错误（比如未闭合的标签、特殊字符未转义），Swagger会解析失败。可以用VS的XML编辑器打开，它会自动提示格式问题。

2. 确保Swagger能扫描到模块化控制器 #

你的WebAPI项目通过AssemblyPart加载控制器，但Swagger默认可能没扫描到这些外部类库的控制器：

• 在AddSwaggerGen中显式指定要包含的控制器程序集，并开启控制器注释：

  var controllerAssembly = Assembly.Load("Test.Modules.UserAccess.Facade");
  // 包含控制器的XML注释
  options.IncludeXmlComments(commentsFile, includeControllerXmlComments: true);
  // 确保Swagger只包含目标程序集的API
  options.DocInclusionPredicate((docName, apiDesc) =>
  {
      var actionAssembly = apiDesc.ActionDescriptor.RouteValues["controller"].GetType().Assembly;
      return actionAssembly == controllerAssembly;
  });
  

• 确认控制器类都标记了[ApiController]和[Route]属性，Swagger依赖这些属性生成文档。

3. 排查JWT安全配置的潜在问题 #

你的Swagger配置了Bearer认证，可能存在配置错误：

• 暂时注释掉安全配置部分，重新启动项目看Swagger是否能正常加载：

  // var securityToken = new Dictionary<string, IEnumerable<string>> { {"Bearer", new string[] { }}, };
  // options.AddSecurityDefinition("Bearer", new ApiKeyScheme { ... });
  // options.AddSecurityRequirement(securityToken);
  

• 如果注释后正常，说明安全配置有问题，检查ApiKeyScheme的参数：比如In = "header"是否为小写，Name = "Authorization"是否和实际请求头一致。

4. 查看详细错误日志 #

Swagger加载失败时，浏览器的开发者工具能帮你找到具体原因：

• 打开浏览器F12，切换到网络标签，刷新页面，找到/swagger/v1/swagger.json的请求，查看返回的状态码和响应内容（比如500错误会包含异常信息）。
• 查看服务器端的应用日志（比如Windows事件查看器、ASP.NET Core日志文件），里面会记录Swagger生成文档时的具体异常，比如找不到文件、XML解析错误等。

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