ASP.NET Core 2.0中SwaggerUI无法加载swagger.json的问题求助

我帮你梳理了几个常见的问题点，结合你的代码来看，应该可以解决swagger.json加载失败的问题：

1. 中间件顺序错误（最可能的原因） #

你的Configure方法里中间件顺序存在冲突和不合理的地方，这会导致Swagger端点或静态资源无法被正确访问：

• UseFileServer已经包含了UseStaticFiles的功能，重复调用UseStaticFiles会造成冗余甚至冲突
• Swagger相关中间件的位置需要在静态文件中间件之后，但要在Mvc之前

修改后的Configure方法代码：

public void Configure(IApplicationBuilder app, IHostingEnvironment environment)
{
    // 开发环境先启用开发者异常页面，方便排查错误
    if (environment.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        // 暂时注释异常处理页面，排查完成后再恢复
        // app.UseExceptionHandler("/Registration/Error");
    }
    else if (environment.IsStaging())
    {
        app.UseDeveloperExceptionPage();
        // app.UseExceptionHandler("/Registration/Error");
    }

    // 只保留一个静态文件服务中间件
    app.UseFileServer();

    // 先注册Swagger核心中间件，用于生成swagger.json
    app.UseSwagger();

    // 注册SwaggerUI，指定路由前缀和swagger.json端点
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.RoutePrefix = "docs";
    });

    app.UseCors("AllowAll");
    app.UseMvc(ConfigureRoutes);
}

2. XML文档路径错误或文件缺失 #

你的Swagger配置中引用了XML注释文件，但路径获取方式在ASP.NET Core 2中已经过时，且未判断文件是否存在，这会导致swagger.json生成失败：

修改ConfigureServices中的SwaggerGen配置：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info
    {
        Title = "Onboarding API",
        Version = "V1",
        Description = "API to generate lead and return the url",
        TermsOfService = "Please see terms and conditions",
        Contact = new Swashbuckle.AspNetCore.Swagger.Contact
        {
            Name = "copa",
            Email = "support@copa.com.au",
            Url = "https://www.copa.com/"
        }
    });

    // 使用IHostingEnvironment获取正确的项目根路径
    var xmlPath = Path.Combine(environment.ContentRootPath, "copa.RegistrationApplication.xml");
    if (System.IO.File.Exists(xmlPath))
    {
        c.IncludeXmlComments(xmlPath);
    }
    else
    {
        // 可选：添加日志提示文件不存在
        // Console.WriteLine($"Warning: XML documentation file not found at {xmlPath}");
    }
});

注意：需要在项目属性→生成→输出中勾选"XML文档文件"，确保文件路径与代码中的一致。

3. 自定义SwaggerUI页面的两个关键问题 #

你的index.cshtml存在两个致命问题：

（1）静态资源路径错误 #

页面中使用的相对路径会因为路由前缀docs而找不到资源，需要改为绝对路径：

<!-- 修改前 -->
<link href='css/typography.css' media='screen' rel='stylesheet' type='text/css' />
<!-- 修改后 -->
<link href='/css/typography.css' media='screen' rel='stylesheet' type='text/css' />

所有css、js、图片资源都需要改成绝对路径（以/开头）。

（2）缺少SwaggerUI加载触发代码 #

初始化SwaggerUi后，必须调用load()方法才会发起swagger.json的请求：

window.swaggerUi = new SwaggerUi({
    url: "/swagger/v1/swagger.json",
    dom_id: "swagger-ui-container",
    supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
    onComplete: function(swaggerApi, swaggerUi){
        if(typeof initOAuth == "function") {
            initOAuth({
                clientId: "your-client-id",
                clientSecret: "your-client-secret-if-required",
                realm: "your-realms",
                appName: "your-app-name",
                scopeSeparator: " ",
                additionalQueryStringParam: {} // 补充缺失的大括号
            });
        }
    }
});

// 关键：添加这行代码触发加载
window.swaggerUi.load();

4. 验证步骤 #

1. 启动项目后，直接访问/swagger/v1/swagger.json，确认能返回正常的JSON内容：
   • 返回404：说明Swagger中间件未正确注册，检查中间件顺序
   • 返回500：说明生成swagger.json出错，查看开发者异常页面的详细信息（比如XML文件不存在）
2. 访问/docs，查看SwaggerUI是否能正常加载swagger.json

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