OpenAPI document generation, how is servers array populated?

[jerchap]

I am trying to transition from using the Swashbuckle nuget to using Microsoft.AspNetCore.OpenApi to generate the OpenAPI json document. What I'm finding is that the exact same web api is generating the document differently on different servers, and as a result either the user experience of the swagger/scalar UI is sub optimal or it doesn't work at all because of how the servers property in the json is populated. On one server, the servers property is populate based on the bindings of the web site, and on another server the server property isn't present at all, which breaks the swagger/scalar UI.

I have two windows 2016 IIS servers. I have deployed a .net 9 web api to both servers to the default web site\POC\WebAPI.
The default web site on both servers has a very similar set of bindings:

Server 1:

Type	Host Name	Port	IP Address
https	mytestserver	443	*
https	mytestserver.mydomain.ca	443	*
https	mytestserver01	443	*
https	mytestserver01.mydomain.ca	443	*
https		443	*

Server 2:

Type	Host Name	Port	IP Address
https	myprodserver	443	*
https	myprodserver.mydomain.ca	443	*
https	myprodserver01	443	*
https	myprodserver01.mydomain.ca	443	*
https		443	*

I've add OpenAPI document generation using both and Microsoft.AspNetCore.OpenApi and Swashbuckle.AspNetCore.

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

//OpenAPI generation using Microsoft.AspNetCore.OpenApi
builder.Services.AddOpenApi();

//OpenAPI generation using Swashbuckle.AspNetCore
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

app.MapOpenApi();
app.MapControllers();

app.Run();

I've deployed the web api to both servers, and I can invoke their endpoints fine.

When I look at the generated open api documents that are generated by Microsoft.AspNetCore.OpenApi generate differently for each server, and I don't know why.

• On server 1, there is a "servers" array property that contains an item for each of the bindings of my web site. the url is absolute, and contains the virtual path of the web api
• On server 2, there is no "servers" property at all

When I look at the generated open api document that are generated by Swashbuckle.AspNetCore the documents generate the same way for both servers

• the servers array property contains a single element, which is a relative url that includes the virtual path of the web api

The result is that if I try to use a UI like Swagger or Scalar, the ui may not work

• On server 1, when using the Microsoft.AspNetCore.OpenApi generated openapi document, the UI works, but I have to choose the server in the UI. Depending on my web site bindings, some of the servers aren't appropriate because I might have a binding with no host name, or for a protocol like msmq
• On server 2, when using the Microsoft.AspNetCore.OpenApi generated openapi document, the UI doesn't work because there is no servers property, and therefore there is no path that includes the virtual path to the web api
• On server 1 or 2, when using the Swashbuckle.AspNetCore generated openapi document, the UI works and I don't have to choose a server because there is only one option, regardless of what bindings are set up.

Microsoft.AspNetCore.OpenAp generated OpenAPI document on server 1:

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

Microsoft.AspNetCore.OpenAp generated OpenAPI document on server 2:

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

Swashbuckle.AspNetCore generated OpenAPI document on server 1 and 2:

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

I like how swashbuckle generates the json because the server url is a relative path to the api, and it doesn't include all the irrelevant bindings. It just works. The Microsoft.AspNetCore.OpenApi seems to populate the servers list based on bindings of the web site, but not in all cases, and some of which might not be relevant for openapi, and it seems to be impacted by server configuration that I am not aware of. Does anyone have any insights on this?

[martincostello]

Maybe this? #61252 (comment)

[jerchap]

Thanks. It's definitely similar, but I don't know if its the same issue or not. Apparently there will be a new release soon, and someone's eluded to that issue being fixed in it

[martincostello]

Yeah, that was me 😉