Fixing ‘Failed to Load API Definition’ Error in SwaggerUI for ASP.NET Core API on IIS

When hosting an ASP.NET Core API, it is not uncommon to encounter a “Failed to load API definition” error in SwaggerUI. This article explores the causes of this error and provides steps to resolve it.

problem
I have an ASP.NET Core API with Swagger OpenAPI and I have added and configured Swagger middleware using the following code snippet.

//adding swagger middleware
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();


//enable the middleware for serving the generated JSON document and the Swagger UI,
app.UseSwagger();
app.UseSwaggerUI(c =>
{
	c.SwaggerEndpoint("/swagger/v1/swagger.json", "DemoAPI v1");
});

After deploying the application as a site in IIS, everything works fine and the Swagger UI works correctly. However, when deploying the same application as an application on an existing site, I get an error “Failed to load API definition”. In the example below, the API is hosted on the “ExceptionLab” site and listens on port 82.

When I browse to the Swagger endpoint of my API, I get a “Failed to load API definition” error.

cause
The root cause of this issue lies in the Swagger Endpoint definition. When inspecting it in the developer console, you will see a 404 error stating that /swagger/v1/swagger.json cannot be found.

Swagger UI is correctly pointing to localhost:82/API, but that page is trying to retrieve swagger.json from the parent site, which causes an error.

way out
The solution to this problem is simple. You need to update your Swagger endpoint definition. You can remove the SwaggerEndpoint entirely and let your application automatically determine the correct URL (this removes the customization option). Or, you can update your endpoint as follows:

app.UseSwaggerUI(c =>
{
	c.SwaggerEndpoint("../swagger/v1/swagger.json", "DemoAPI v1");
});

Add two additional points...” at the beginning of the path as shown in the example above. This adjustment will point to the swagger.json file correctly, resolving the “Failed to load API definition” error and allowing SwaggerUI to load correctly.