How to fix swagger and openApi version issue

Question

Why am I getting "Unable to render this definition. The provided definition does not specify a valid version field. Supported version fields are swagger: 2.0 and openapi: 3.x.y" when running Swagger in my ASP.NET Core project?

Answer 1

Hello @prince ,

You’ll see that message when Swagger UI isn’t receiving a valid OpenAPI/Swagger document. A quick way to fix it is to verify the document exists and that your app generates it correctly.

Try this minimal setup (ASP.NET Core + Swashbuckle):

// Program.cs
using Microsoft.OpenApi.Models;
 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    // The UI title/version label; not the OpenAPI version
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
 
var app = builder.Build();
 
app.UseSwagger(); // Generates /swagger/v1/swagger.json
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
 
app.MapControllers();
app.Run();

Then check these specifics:

• Open /swagger/v1/swagger.json directly in the browser. It must begin with either:
  • { "openapi": "3.x.y", ... } or { "swagger": "2.0", ... }
• If you see HTML or a 404, the UI is pointing to the wrong path (adjust the SwaggerEndpoint to your base path if the app is behind a proxy or virtual directory).
• Don’t run both Swashbuckle and NSwag at the same time; use one generator.
• Ensure no custom middleware/filters rewrite or strip the top-level "openapi"/"swagger" property.
• Order matters: call app.UseSwagger() before app.UseSwaggerUI() and before mapping controllers.

If the raw JSON starts with "openapi" or "swagger" and loads at the configured path, Swagger UI will render correctly.

Hope this solves your problem.

Answer 2

1. Your Swagger UI points to the correct endpoint: print shop near me

c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

The generated JSON has either "swagger": "2.0" or "openapi": "3.x.y".

Usually fixing the Version in SwaggerDoc resolves it.

Answer 3

You’re getting that error because the Swagger JSON your app is serving is missing the required version field. Make sure:

In AddSwaggerGen, you specify a version:

c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });