Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

OpenAPI does not work in an ASP.NET Core minimal API

Error404 Not Found at /openapi/v1.json

Short answer

ASP.NET Core 9 and later generate OpenAPI documents with the Microsoft.AspNetCore.OpenApi package: AddOpenApi registers it and MapOpenApi serves /openapi/v1.json. The package has no UI. Install the package, map the endpoint, and add a UI package only if you want a page.

  • Applies to .NET 9, .NET 10, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check the package is installed.

    dotnet list package | grep -i openapi
  2. 2Match what you see, then jump to its fix

    1. 1The compiler cannot find AddOpenApi or MapOpenApi.The Microsoft.AspNetCore.OpenApi package is not installedFix
    2. 2404 for /openapi/v1.json outside the Development environment.The endpoint is mapped only in Development, or the wrong URL is usedFix
    3. 3/swagger returns 404 although the JSON document works.There is no Swagger page because the package ships no UIFix

What does the error look like?

  • 404 Not Found at /openapi/v1.json

Cause 1 of 3

The Microsoft.AspNetCore.OpenApi package is not installed

1Check

The built-in support comes from this package.

dotnet list package | grep Microsoft.AspNetCore.OpenApi

2Fix

Install the package and register and map it.

dotnet add package Microsoft.AspNetCore.OpenApi

// Program.cs
builder.Services.AddOpenApi();
app.MapOpenApi();

3Verify

The project builds.

dotnet build

Confirmed by learn.microsoft.com

Did this fix it?

Cause 2 of 3

The endpoint is mapped only in Development, or the wrong URL is used

1Check

The documented sample calls MapOpenApi inside an IsDevelopment check, and the document is served at /openapi/{documentName}.json.

echo $ASPNETCORE_ENVIRONMENT

2Fix

Run in Development, or map the endpoint on purpose for other environments. Request the documented path.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

3Verify

Open the document.

curl -s http://localhost:5000/openapi/v1.json | head -c 200

Confirmed by learn.microsoft.com

Did this fix it?

Cause 3 of 3

There is no Swagger page because the package ships no UI

1Check

The package does not ship visualization of the document.

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5000/swagger

2Fix

Add Swashbuckle.AspNetCore.SwaggerUi (or Scalar.AspNetCore) and keep the UI in Development.

dotnet add package Swashbuckle.AspNetCore.SwaggerUi

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/openapi/v1.json", "v1");
});

3Verify

Open /swagger.

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5000/swagger

Confirmed by learn.microsoft.com

Did this fix it?

How do I stop it coming back?

  • Expose OpenAPI UIs only in Development, as the docs advise.
  • Pin the document path you share with client generators.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

Chrome says my localhost certificate is invalid

NET::ERR_CERT_DATE_INVALID

A local HTTPS certificate is rejected for one of three reasons: it was never trusted, it expired (ASP.NET Core development certificates last about 12 months), or a certificate you made yourself has no subject alternative name for localhost.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.