OpenAPI does not work in an ASP.NET Core minimal API
404 Not Found at /openapi/v1.jsonShort 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.
Fix it fast
1Find out which cause you have
Check the package is installed.
dotnet list package | grep -i openapi2Match what you see, then jump to its fix
- 1
The compiler cannot find AddOpenApi or MapOpenApi.The Microsoft.AspNetCore.OpenApi package is not installedFix - 2
404 for /openapi/v1.json outside the Development environment.The endpoint is mapped only in Development, or the wrong URL is usedFix - 3
/swagger returns 404 although the JSON document works.There is no Swagger page because the package ships no UIFix
- 1
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.OpenApi2Fix
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 buildConfirmed by learn.microsoft.com
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_ENVIRONMENT2Fix
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 200Confirmed by learn.microsoft.com
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/swagger2Fix
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/swaggerConfirmed by learn.microsoft.com
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
npm start runs, but the browser does not refresh when you save a file
Saving a file does nothing while npm start is running
The watcher behind npm start is not seeing your edit.
4 causes, each with a fixWeb apps
django-tailwind cannot find the npm executable (cPanel, Windows, Linux)
CommandError raised by the tailwind management command about npm
django-tailwind runs npm as a subprocess, and Python sometimes cannot find it.
3 causes, each with a fixWeb 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 fixWeb apps
Node.js fails with uv_cwd ENOENT when its folder is gone
npm, node or next fails at start in a terminal whose folder was removed
uv_cwd is how Node.js asks the operating system for its current working directory.
2 causes, each with a fixWeb apps
Playwright cannot open a headed browser on a Linux server or in Docker
npx playwright test --headed shows no window on a Linux server
A headed browser needs a display, and a Linux server or container has none.
3 causes, each with a fixWeb apps
The shell says pnpm: command not found
npx next dev works, but pnpm dev or pnpm install is not found
The shell cannot find a pnpm executable on PATH.
3 causes, each with a fix