.NET 6 Web API多环境Swagger URL配置及访问报错排查

我看你现在遇到的问题是想统一开发、测试、生产环境的Swagger访问路径为类似https://devurl/api/abc/swagger.yaml的形式，但当前配置运行后出现找不到页面的报错。咱们先分析下问题出在哪，再给你调整后的解决方案。

问题根源 #

你当前的配置存在两个核心问题：

• 路由前缀不统一：开发环境没有设置RoutePrefix，默认入口是/swagger/index.html，但非开发环境把入口改成了/api/abc/index.html，如果你在非开发环境（或者不小心切换了环境变量）还访问旧的/swagger/index.html，肯定会找不到页面。
• Swagger文档路径不匹配：非开发环境中你设置了SwaggerEndpoint("swagger/v1/swagger.yaml", "API V1")，这是相对路径，当SwaggerUI的路由前缀是api/abc时，它会尝试加载/api/abc/swagger/v1/swagger.yaml，但实际Swagger文档默认生成在/swagger/v1/swagger.yaml，路径不对应导致加载失败。

调整后的解决方案 #

我们可以统一所有环境的Swagger配置，让文档路径和UI入口完全匹配你的需求。修改后的代码如下：

public static void ConfigureSwaggerMiddleware(this WebApplication app)
{
    // 配置Swagger文档的生成路径，让它直接输出到/api/abc/swagger/{documentName}/swagger.yaml
    app.UseSwagger(c =>
    {
        c.RouteTemplate = "api/abc/swagger/{documentName}/swagger.yaml";
    });

    // 统一设置SwaggerUI的入口路由
    app.UseSwaggerUI(c =>
    {
        // SwaggerUI的访问入口为 https://{domain}/api/abc
        c.RoutePrefix = "api/abc";
        // 用相对路径指向刚才配置的文档地址，确保UI能正确加载
        c.SwaggerEndpoint("./swagger/v1/swagger.yaml", "API V1");
    });

    // 如果你需要在开发环境保留原来的/swagger入口方便调试，可以解开下面的注释
    // if (app.Environment.IsDevelopment())
    // {
    //     app.UseSwaggerUI(c =>
    //     {
    //         c.SwaggerEndpoint("/swagger/v1/swagger.yaml", "API V1 (Default)");
    //     });
    // }
}

关键调整说明 #

1. 统一文档生成路径：通过c.RouteTemplate把Swagger文档直接生成在/api/abc/swagger/v1/swagger.yaml，完全匹配你想要的URL格式。
2. 统一UI入口：所有环境的SwaggerUI入口都是https://{domain}/api/abc/index.html，不用再区分环境切换地址。
3. 相对路径匹配：SwaggerEndpoint使用./swagger/v1/swagger.yaml，因为UI已经在api/abc路由下，相对路径会自动指向正确的文档地址。

验证方式 #

启动项目后，直接访问https://localhost:7120/api/abc/index.html，就能正常打开SwaggerUI，并且能正确加载swagger.yaml文档了。如果开启了开发环境的额外入口，也可以继续用https://localhost:7120/swagger/index.html访问。

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