ASP.NET Core 9 API：OpenAPI/Scalar.AspNetCore服务器列表与绑定显示异常

部署环境与IIS配置 #

开发的ASP.NET Core 9 Web API部署在两台配置一致的Windows Server 2016 Data Center服务器（IIS运行），默认网站绑定如下：

OpenAPI生成与Scalar表现问题 #

Microsoft官方推荐用Scalar替代Swashbuckle，但实际部署后Scalar表现不符合预期。尽管服务器配置一致，生成的OpenAPI JSON却存在明显差异：

• 服务器1：文档包含servers数组，对应5条绑定的绝对URL（带虚拟路径）
• 服务器2：文档无servers属性
• Swashbuckle：生成含虚拟路径的单个相对URL的servers节点，为理想方式

服务器1的OpenAPI JSON #

{
  "openapi": "3.0.1",
  "info": {
    "title": "WebAPI | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://serverdev01:443/WEBSERVICES/TEMPLATES/WEBAPI"
    },
    {
      "url": "https://serverdev01.mydomain.ca:443/WEBSERVICES/TEMPLATES/WEBAPI"
    },
    {
      "url": "https://serverdev:443/WEBSERVICES/TEMPLATES/WEBAPI"
    },
    {
      "url": "https://serverdev.mydomain.ca:443/WEBSERVICES/TEMPLATES/WEBAPI"
    },
    {
      "url": "https://*:443/WEBSERVICES/TEMPLATES/WEBAPI"
    }
  ],
  "paths": {
    "/api/Myfunc": {
      "get": {
        ...
      }
    }
  },
  ...
}

服务器2的OpenAPI JSON #

{
  "openapi": "3.0.1",
  "info": {
    "title": "WebAPI | v1",
    "version": "1.0.0"
  },
  "paths": {
    "/api/Myfunc": {
      "get": {
        ...
      }
    }
  },
  ...
}

使用Swashbuckle时的OpenAPI JSON #

{
  "openapi": "3.0.1",
  "info": {
    "title": "WebAPI | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "/WebServices/Templates/WebAPI"
    }
  ],
  "paths": {
    "/api/Myfunc": {
      "get": {
        ...
      }
    }
  },
  ...
}

Web API代码实现 #

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);    

builder.Services.AddControllers();
// 使用Microsoft的OpenAPI生成OpenAPI JSON文档
builder.Services.AddOpenApi();
// 使用Swashbuckle生成OpenAPI JSON文档
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    // 添加Scalar的OpenAPI UI
    app.MapOpenApi();
    app.MapScalarApiReference();
    // 添加Swashbuckle的OpenAPI UI
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

Scalar UI访问表现差异 #

• 服务器1：UI列出所有IIS绑定并包含API虚拟路径，可调用接口，但需选择服务器，可能显示不可用绑定
  
• 服务器2：UI仅显示访问用DNS别名，无虚拟路径，无法调用API
  
• Swagger UI：完全正常

核心疑问 #

无法理解MapOpenApi行为为何在两台服务器上不一致，以及为何不能在server元素中使用相对URL。

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