Hmmm... API Versioning doesn't care about nor has any direct references to OpenAPI, Swagger UI, or Swashbuckle. My best guess, without more information, is that you have a route that maps over ~/swagger or you have convention-based routing somewhere. In order to see this problem, the requested path would have to match something in the route table.

Another possibility is that the order of the middleware is incorrect. Assuming you are using controllers, UseSwagger() and UseSwaggerUI must come before MapControllers. The fact that the behavior is different, in different environments, suggestions you have some type of conditional or branching logic in the configuration.

Thanks for your response. I've found that the issue doesn't actually behave differently in different environments, which makes a lot more sense. The reason it was working in Brave was because the swagger files were cached. After clearing cache it fails to load on Brave too.

My best guess, without more information, is that you have a route that maps over ~/swagger or you have convention-based routing somewhere. In order to see this problem, the requested path would have to match something in the route table.

I use convention-based routing for all of my OData controllers. Only the error controllers use attribute routing.
image

Another possibility is that the order of the middleware is incorrect. Assuming you are using controllers, UseSwagger() and UseSwaggerUI must come before MapControllers.

UseSwagger and UseSwaggerUI do come before MapControllers, so I'm going to have to try to narrow down the issue. Here's my app config:

Dim oApp = oBuilder.Build()
' Configure the HTTP request pipeline.
oApp.UseSerilogRequestLogging()
oApp.UseHttpsRedirection()
If oApp.Environment.IsDevelopment() Then
 ' Navigate to ~/$odata to determine whether any endpoints did not match an odata route template
 oApp.UseODataRouteDebug
 oApp.UseExceptionHandler("/error-development")
Else
 oApp.UseExceptionHandler("/error")
End If
oApp.UseSwagger()
oApp.UseSwaggerUI(Sub(o)
 For Each oDescription In oApp.DescribeApiVersions()
 Dim sURL = $"/swagger/{oDescription.GroupName}/swagger.json"
 Dim sName = oDescription.GroupName.ToUpperInvariant()
 o.SwaggerEndpoint(sURL, sName)
 Next
 End Sub)
oApp.UseCors()
oApp.UseStaticFiles()
oApp.UseAuthentication()
oApp.UseAuthorization()
oApp.MapControllers()
oApp.MapHub(Of cDataHub)("/signalr/data")
oApp.MapHub(Of cVOIPHub)("/signalr/voip")
oApp.Run()

I've managed to track down the method causing the issue:
If I comment out: o.AddRouteComponents("v{version:apiVersion}"), Swagger UI works (but I lose the API version in the URLs obviously), if I uncomment the line, Swagger UI imports die and I get the blank screen.

oBuilder.Services.AddApiVersioning(Sub(o)
 o.ReportApiVersions = True
 End Sub) _
 .AddMvc() _
 .AddOData(Sub(o)
 'o.AddRouteComponents("v{version:apiVersion}") <<<<<<<<<<<<<<<<<<<<<< Works if commented out
 o.ModelBuilder.ModelBuilderFactory = Function() New cCamelCaseODataModelBuilder()
 End Sub) _
 .AddODataApiExplorer(Sub(o)
 o.GroupNameFormat = "'v'VVV"
 o.SubstituteApiVersionInUrl = True
 End Sub)

The above "works", but I lose url versioning:
image

image

oBuilder.Services.AddApiVersioning(Sub(o)
 o.ReportApiVersions = True
 End Sub) _
 .AddMvc() _
 .AddOData(Sub(o)
 o.AddRouteComponents("v{version:apiVersion}") ' <<<<<<<<<<<<<<<<<<<<<<<<<<<< Breaks Swagger UI
 o.ModelBuilder.ModelBuilderFactory = Function() New cCamelCaseODataModelBuilder()
 End Sub) _
 .AddODataApiExplorer(Sub(o)
 o.GroupNameFormat = "'v'VVV"
 o.SubstituteApiVersionInUrl = True
 End Sub)

The above means Swagger UI is broken, but I now have working url versioning:
image

image

This issue only appears if the API version segment is the "root segment".
That is, o.AddRouteComponents("v{version:apiVersion}") breaks Swagger UI,
but, o.AddRouteComponents("api/v{version:apiVersion}" works.

We were planning on having the API accessed via a subdomain api.ourdomain.com, so we didn't need api to appear in the path itself.
Does this appear to be an unsupported configuration, or are we looking at a bug?

Strangely, if the swagger route has a multi-part prefix, then the API can have no prefix before the version:
That is:
o.AddRouteComponents("v{version:apiVersion}")
with a single-part swagger route prefix:

oApp.UseSwagger(Sub(o)
 o.RouteTemplate = "docs/{documentName}/docs.json"
 End Sub)
oApp.UseSwaggerUI(Sub(o)
 o.RoutePrefix = "docs"
 For Each oDescription In oApp.DescribeApiVersions()
 Dim sURL = $"/docs/{oDescription.GroupName}/docs.json"
 Dim sName = oDescription.GroupName.ToUpperInvariant()
 o.SwaggerEndpoint(sURL, sName)
 Next
 End Sub)

breaks Swagger UI

But:
o.AddRouteComponents("v{version:apiVersion}")

with a multi-part swagger route prefix:

oApp.UseSwagger(Sub(o)
 o.RouteTemplate = "docs/api/{documentName}/docs.json"
 End Sub)
oApp.UseSwaggerUI(Sub(o)
 o.RoutePrefix = "docs/api"
 For Each oDescription In oApp.DescribeApiVersions()
 Dim sURL = $"/docs/api/{oDescription.GroupName}/docs.json"
 Dim sName = oDescription.GroupName.ToUpperInvariant()
 o.SwaggerEndpoint(sURL, sName)
 Next
 End Sub)

works fine.

There could be some edge case combination with Swashbuckle + OData + API Versioning

I expected there was always going to be some conflicts found eventually 😅

Is this example all current libraries and .NET? When I get a little time to carve out, I'll try to repro things.

We're using:

• .NET 7 (LTS)
• Asp.Versioning.Mvc 7.1.0 (Latest compatible is 7.1.1, just haven't updated)
• Asp.Versioning.Mvc.ApiExplorer 7.1.0 (Latest compatible)
• Asp.Versioning.OData 7.1.0 (Latest compatible)
• Asp.Versioning.OData.ApiExplorer 7.1.0 (Latest compatible)
• Microsoft.AspNetCore.OData 8.2.3-Nightly202312181316 (I'm using this because they implemented IEEE754Compatible in the accept header here) - Looks like 8.2.3 is stable now anyway (Latest 8.2.4)
• Swashbuckle.AspNetCore 6.2.3 (Latest 6.5.0) - Not sure why we're using this version, possibly just what was in the initial VS template.
• Swashbuckle.AspNetCore.Annotations 6.5.0 (Latest)

Of course you could go with a RESTful API, not use a version in the URL segment, and it would just work. 😜 ...but I get it,. Some people really insist or want it that way. If you want to version by URL, it should work as expected. 😸

Ha! We went back and forth over this for a while, but it seems that version in the URL is common, popular, easy to use and has great compatibility, so that's why we chose it 😁

I think that for us, we're going to switch away from the subdomain and have the API routes under api/v{version:apiVersion} and the Swagger stuff under docs/api, as this combination makes sense semantically for us and doesn't conflict.

Hopefully I've pointed you in the right direction for your debugging, if you get a chance to find the cause.

Thanks for the excellent library!