如何在ASP.NET 5项目的NSwag配置中有效设置ServerUrl？

我明白你的困惑——NSwag的ServerUrl属性很容易被误解，它其实不是用来设置API请求的目标服务器地址的，而是用来配置Swagger UI自身的部署基础路径（比如当UI部署在子域名或子路径下时）。这就是为什么你的设置完全没生效的原因，API请求依然会指向当前主机地址。

要正确设置API请求的目标服务器地址，你需要在生成OpenAPI文档的步骤中配置Servers，而不是在Swagger UI的设置里。下面是具体的解决步骤：

1. 在服务配置中添加OpenAPI服务器地址 #

找到你项目中AddOpenApiDocument的配置代码（通常在Program.cs或Startup.cs里），添加AddServer配置：

services.AddOpenApiDocument(settings =>
{
    settings.Title = "你的API名称";
    // 配置API请求的目标服务器地址
    settings.AddServer(new OpenApiServer { Url = "https://XXXXX.YYYYY.com/ZZZZ" });
    
    // 如果需要添加多个服务器（比如开发/生产环境），可以多次调用AddServer
    // settings.AddServer(new OpenApiServer { Url = "https://localhost:5001", Description = "开发环境" });
});

2. 保留原有的Swagger UI路径转换代码 #

你之前写的TransformToExternalPath是用来解决Swagger JSON文件的路径识别问题，这个可以继续保留，不影响服务器地址的配置：

app.UseSwaggerUi3(settings => {
    // 注意：这里的ServerUrl可以留空或者根据UI部署路径调整，不是API请求地址
    // settings.ServerUrl = "如果UI部署在子路径，这里填UI的基础路径";
    settings.TransformToExternalPath = (url, request) => {
        string outputUrl;
        if (url.EndsWith(".json") || request.Path.ToString().EndsWith("/"))
            outputUrl = ".." + url;
        else
            outputUrl = request.PathBase + "." + url;
        return outputUrl;
    };
});

3. 验证配置是否生效 #

启动应用后打开Swagger UI页面，你会在页面顶部看到一个Servers下拉框，里面会显示你配置的https://XXXXX.YYYYY.com/ZZZZ地址。选择这个服务器后，所有API请求都会自动指向该地址，而不是当前主机地址。

补充：动态设置服务器地址 #

如果需要根据环境（开发/生产）动态切换服务器地址，可以结合配置文件或环境变量：

// 假设你在appsettings.json里配置了ApiServerUrl字段
var serverUrl = Configuration["ApiServerUrl"] ?? "https://localhost:5001";

services.AddOpenApiDocument(settings =>
{
    settings.Title = "你的API名称";
    settings.AddServer(new OpenApiServer { Url = serverUrl });
});

这样就能根据不同环境自动加载对应的服务器地址了。

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