Resolved: Swagger Failed to load API definition. Fetch error

Today in this article, we will see a few resolution steps for errors “Swagger Failed to load API definition. Fetch error”

Issue Description

Swagger Open API documentation gives the below error in .NET API etc.

“Failed to load API definition. Fetch error undefined /swagger/v1/swagger.json”

It is observed that Swagger API documentation/description when it runs in publish mode i.e. hosted on IIS or Cloud Server or other servers produces the error like “Failed to load API definition” with undefined/swagger/v1/swagger.json error.

Resolution – Failed To Load API Definition

Before applying this fix, I would recommend you validate the swagger implementation with the below article,

• ASP.NET Core 3.1 or 6.0 – Add Swagger OpenAPI V3.0 specification documentation

Please make sure you verify the below points or steps,

The above steps might resolve your issue in any order depending on the type of issue you facing.

Resolution 1- Resolving Conflicting actions

Please make sure the API doesn’t contain any conflicting action. This is the most common cause of this issue.

Conflicting action could be using the same routes or the same HTTP verb abbreviations for GET, POST routes, etc.

To be on the safer side, you can very much use the below flag to control that behavior,

c.ResolveConflictingActions(x => x.First());

Resolution 2 – Missing HTTP Attributes

Please make sure all controller methods are attributed with proper HTTP attributes Example- [HttpGET] or [HttpPost] etc.

Any missing attribute accidentally on any such public method could cause the error.

If the issue persists then please apply the below Resolution – 5 to resolve the issue.

Resolution 3- CORS or CSP issues

Please check if the hosting server allows CORS request processing.

Also, it is important swaggers UI-related resources like CSS or stylesheets are accessible from your server.

Swagger accessing resources from external sites may be not accessible due to CSP issues as explained in this article.

This is a common issue on a cloud server where you may need to whitelist a few domains.

Resolution 4 – Title and Version in Swagger

Swagger Document is defined with proper Title and Version details, as both are required parameters.

Resolution 5 – Use the correct Swagger configuration

Please, note that Swagger JSON will be exposed at the following route as per default behavior.

If you are using a custom route or prefix, then the route MUST include the {documentName} parameter.

To fix the issue, please update the UseSwagger() as below,

app.UseSwagger(c =>
{  c.RouteTemplate = "<custom-name>/swagger/{documentName}/swagger.json";   }
);

Example,

 


c.RouteTemplate = "MyTestService/swagger/{documentName}/swagger.json";  

The above changes also need to be reflected in SwaggerUI middleware.

Please update the UseSwaggerUI method will be as follows,

app.UseSwaggerUI(c =>
             {
                 c.SwaggerEndpoint("/<custom-name>/swagger/v1/swagger.json", "TestService");
             });

Example:

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

Please note that in Swaggerendpoint() method ‘documentName’ value is cases sensitive.

In fact, documentName is case sensitive anywhere else if referenced.

This documentName is generally a Group Name associated with API version

Example: It won’t work for V1 but works for v1.

If using RoutePrefix in API then it can be defined as below,

Example only if using RoutePrefix,

c.RoutePrefix= "MyTestService/swagger"

Here MyTestService is my service name.

Please see below the complete implementation,

Finally, Swagger runs successfully locally and in any hosting environment like IIS or Azure Cloud, etc.

Resolution 6 – Other Issues?

For any other issues, please use your browser debug tools to verify for specific errors.

For example – Google Chrome Dev tools ( F12), or Edge Developer tools to verify the exact error causing the issue.

Please verify the Console -> Network tab to validate the exact error.

Other References:

Add swagger to ASP.NET Core API in simple 2-3 steps,

• Swagger API Documentation in .NET Core 6 or 3.1

• API versioning support for Swagger/OpenAPI

Did I miss anything else in these resolution steps?

Did the above steps resolve your issue? Please sound off your comments below!

Happy Coding !!

Please bookmark this page and share it with your friends. Please Subscribe to the blog to receive notifications on freshly published(2024) best practices and guidelines for software design and development.