Support root-relative paths in endpoint paths in Swagger UI

In a reverse-proxy environment, the base path can often include multiple segments:

https://myapi.com/some/root/path

The correct way to set up custom base paths is to use app.UsePathBase:

// in Startup.Configure
public void Configure(IApplicationBuilder app) {
    app.UsePathBase("/some/root/path");
}

When you do this, your new “application root” path is the above path. Any place you use ~/ in your paths will add that request base path. When using IIS integration, this is all taken care of for you:

https://github.com/aspnet/AspNetCore/blob/master/src/Servers/IIS/IISIntegration/src/WebHostBuilderIISExtensions.cs#L43

I found, however, that not all pieces in the SwaggerUI support these alternate application roots.

If you do this:

app.UsePathBase("/some/root/path");
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(options => {
     options.SwaggerEndpoint("swagger/v1/swagger.json", "My API V1");
});

Then my swagger JSON is correctly served by /some/root/path/swagger/v1/swagger.json and the UI is served at /some/root/path/swagger/index.html.

However, it can’t find the swagger JSON off the relative path. It assumes a relative path off of the current UI /some/root/path/swagger/swagger/v1/swagger.json.

The only way I can get this to work is manually include the root path in the URLs:

app.UsePathBase("/some/root/path");
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(options => {
    options.SwaggerEndpoint("/some/root/path/swagger/v1/swagger.json", "My API V1");
});

If my application’s path base is set, then everything should work seamlessly, I shouldn’t need to configure anything. All the middleware does is alter the Request.BasePath part. Additionally, that root path could come in from configuration somewhere, and I don’t want to have my Swagger UI aware of this.

Ideally, I could use root-relative paths:

app.UsePathBase("/some/root/path");
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(options => {
    options.SwaggerEndpoint("~/swagger/v1/swagger.json", "My API V1");
});

This doesn’t work, however, as the URL requested becomes:

/some/root/path/swagger/~/swagger/v1/swagger.json.

Note that I do not need to specify the RoutePrefix, since that part does respect the request base path.

[domaindrivendev]

The path that you provide to SwaggerEndpoint is relative to the Swagger UI page. Therefore, you should be able to make the whole setup proxy / virtual path agnostic with the following configuration:

app.UsePathBase("/some/root/path");
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(options => {
    options.SwaggerEndpoint("v1/swagger.json", "My API V1");
});

[cawoodm]

IMO no web application should care what it’s final external path is. It should always work relative to itself and never assume that / is the root. The reason is that an app should work in front of and behind a reverse proxy. The suggestions above (UsePathBase) mean swagger will ONLY work behind a reverse proxy. I am pretty sure if Swagger is careful with paths (never referencing / but only ./) this should not be a problem.

Alternatively swagger should detect (in the browser) that, although it’s been configured to serve /api/ internally it has been externally started from /extpath/api/ and work accordingly.