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,
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,
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.
Thank you for the fix. It took me lot of time before untill found your article.
Thanks Rick. Glad it helped you !
Thank you !
You welcome Luis!
Solution for my case was: I have controller with 2 methods, both with THE SAME url. It caused a conflict and mentioned error.
Solution is to make url distinguish for every method.
Hi Wello, THank you for your inputs. Yes, that’s one of the scenarios too. We should not have routes conflicting with each other. I did mention the same by using c.ResolveConflictingActions(x => x.First()) we can address it easily.
Thank you!!! Saved me a ton of time looking around. Very good instructions.
Thanks, Ron for the great feedback. Glad it helped you!
still does not work. get the same error Failed to load API definition (undefined MyTestService/swagger/v1/swagger.json)”. My API includes OData too by the way.
Hello Akshay,
Could you please check if OpenAPIInfo objecs Title and Version properties are defined corectly as they are mandatory.
yes, i did the same as the above screenshot and followed your tutorial for this issue. Only difference my my route prefix which is string.Empty.
//This is in my Startup ConfigureServices
services.AddSwaggerGen(c =>
{
c.SwaggerDoc(“v1”, new OpenApiInfo { Title = “MyTestService”, Version = “v1″, });
var xmlFile = $”{Assembly.GetExecutingAssembly().GetName().Name}.xml”;
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
//This is in my Startup
app.UseSwagger(c =>
{
c.RouteTemplate = “MyTestService/swagger/{documentName}/swagger.json”;
});
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint(“/MyTestService/swagger/v1/swagger.json”, “TestService”);
c.RoutePrefix = string.Empty;
});
Some objects in the Swagger specification may be declared and remain empty, or completely be removed, even though they are inherently the core of the API documentation.
Hello Stremove,
Yes. Few object and few properties are are not mandatory and can be ignored but few are required always. For example in OpenAPIInfo object Title and Version are mandatory.
Finally , worked for me … it took me whole day to figure this out until I read this article.
Thanks Jonathan. Glad it helped you!
Hi,
I did exactly as you explained but cannot get it to work. I don’t know if the problem is because I’m using IIS to develop.
Regards.
Hi Rodrigo – Thanks for your query.
Please check all the steps as mentioned above.Apart from that
if using ASP.NET Core 2.2 – c.SwaggerDoc(“v1”, new Info { Title = “MyTestService”, Version = “v1” } verify if it is defined properly.
We do get an error if we miss any of these required fields.
Similarly if using ASP.NET Core > 3.0, please verify
c.SwaggerDoc(“v1″, new OpenApiInfo { Title =”MyTestService”, Version = “v1”, });[/cc]
Hi ,dont work for me ,the “MyTestService” is the name off project ?
My project name like “yyyy.Services.Provider” and i use Core 3.1
Thanks
Hello SAD , thanks for your query. Here “MyTestService” is a service name.
The above should work in .NET Core 3.1 as well.
Please make sure to add register swagger using AddSwaggerGen and SwaggerDoc methods properly.
Worked for me! Thank you.
Thank you Alistair. Appreciate your feedback.
Thanks alot . Worked for me for 2.2 version. I had exact similar issue on aws hosted service.
searched and implemented lot of suggestions from other articles but nothing helped except this.
Kudos to you…
Hello Maruthi- I am glad this article helped you resolve the issue. Thanks for your comments, it meant a lot. Keep visiting the blogs and keep commenting.
I try above fix but I still have an issue. However I am using NSwag UI for API definition.
Hello Anita- Thanks for your query. Could you please elaborate on the error? Please visit this article on NSwag for your reference:https://thecodebuzz.com/nswag-swagger-api-documentation-in-net-core/
Hope it helps.
Worked seamlessly…thank you buddy for the solution.
Thank you! Happy to help you.
Thank you . Worked for me with Route prefix and above changes.
Thanks for your comments and confirmation.
Thank you . Worked for me for 2.2 version. I had exact similar issue on Azure hosted service.