skip to content

In ASP.NET Core 10, what do AddOpenApi and MapOpenApi do, and at which URL is the default OpenAPI document served?

level: juniorimportance: must knowfreq 70%

answer

  1. Microsoft.AspNetCore.OpenApi package
  2. one document per name, default v1
  3. /openapi/{documentName}.json
  4. template maps it only in Development
  5. a document, not a UI

basics

~20 s

AddOpenApi registers ASP.NET Core's built-in OpenAPI generator for a document named v1, and MapOpenApi adds a GET endpoint that builds and serves it at /openapi/v1.json. The webapi template maps it only in Development and ships no UI.

solid answer

~40 s

`builder.Services.AddOpenApi()` comes from the `Microsoft.AspNetCore.OpenApi` package. It registers the generator for one document, named `v1` unless you pass a name, and calls `AddEndpointsApiExplorer()` itself so Minimal API endpoints are discovered. `app.MapOpenApi()` maps `GET /openapi/{documentName}.json`: a request builds the document from the endpoints' metadata and writes it as JSON, so the default URL is `/openapi/v1.json`, and the endpoint leaves itself out of the document. Since .NET 9 the `webapi` template adds exactly this pair, wraps `MapOpenApi()` in `if (app.Environment.IsDevelopment())` and no longer references Swashbuckle. Nothing renders the JSON: you add Scalar or Swagger UI on top. In .NET 10 the document is OpenAPI 3.1 unless you choose otherwise.

code

csharp · 17 lines
csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();             // document "v1"
builder.Services.AddOutputCache();

var app = builder.Build();

app.UseOutputCache();
app.MapOpenApi().CacheOutput();           // GET /openapi/v1.json, in every environment

app.MapGet("/flights/{flightNumber}/status", (string flightNumber) =>
        new FlightStatus(flightNumber, "B12", "Boarding"))
   .WithName("GetFlightStatus");

app.Run();

public record FlightStatus(string FlightNumber, string Gate, string State);

go deeper

for a junior

Recall the pair: AddOpenApi registers the generator, MapOpenApi serves /openapi/v1.json, and the template maps it only in Development with no UI attached.

for a middle

Explain the defaults: document name v1, the route pattern, lower-cased names, the 404 for an unknown name, and how ShouldInclude splits endpoints between documents by group name.

for a senior

Show you treat exposing the document in Production as a decision: cache it with output caching, or generate it at build time, and keep internal endpoints in a separate document.

for a principal

Weigh serving the contract from the running app against publishing a build-time artifact that reviewers diff, and decide who owns the published contract of a public API.

## What the two calls register An **OpenAPI document** is a machine-readable description of an HTTP API: its paths, operations, parameters, request bodies, responses and schemas. Since .NET 9, ASP.NET Core can produce one by itself through the `Microsoft.AspNetCore.OpenApi` package, and the `webapi` template references that package. - `builder.Services.AddOpenApi()` registers the generator for a single document. With no argument the document is named **`v1`**; `AddOpenApi("internal")` registers another one. Each document gets its own keyed singleton services and its own `OpenApiOptions`, so its version, filter and transformers are configured separately. - `AddOpenApi` calls **`AddEndpointsApiExplorer()`** internally. ApiExplorer is the layer that turns endpoints into descriptions, so you do not need to add it yourself for Minimal APIs. - `app.MapOpenApi()` maps a **GET endpoint** with the route pattern `/openapi/{documentName}.json`. On a request it builds the named document from endpoint metadata, serializes it and returns it. The endpoint calls `ExcludeFromDescription()` on itself, so it never appears in the document it serves. ## Defaults worth knowing | Setting | Default in ASP.NET Core 10 | |---|---| | Document name | `v1` (names are lower-cased on registration and lookup) | | Route | `/openapi/{documentName}.json`, so `/openapi/v1.json` | | Format | JSON; a pattern ending in `.yaml` or `.yml` serves YAML | | OpenAPI version | 3.1 (`OpenApiOptions.OpenApiVersion`) | | `info.title` | `"{ApplicationName} \| v1"` | | `info.version` | `1.0.0` | | Which endpoints | those whose group name is null or equals the document name | A request for a name that was never registered, such as `/openapi/v2.json`, gets **404** with a plain-text message saying no document with that name was found. ## What the template gives you The .NET 10 `webapi` template writes: 1. `builder.Services.AddOpenApi();` 2. `if (app.Environment.IsDevelopment()) { app.MapOpenApi(); }` So the document is reachable on a developer machine and **not** in Production unless you move the call. Swashbuckle was removed from the templates in .NET 9; it remains a community package you can add. Nothing in the template renders the JSON as an interactive page. Scalar or Swagger UI is added separately and simply points at `/openapi/v1.json`. ## Publishing it for a public API For a public flight-status API, the published contract is part of the product, so exposing the document in Production is a deliberate decision rather than an accident: - Call `app.MapOpenApi()` outside the environment check. - The document is generated when the endpoint is requested. The docs suggest caching it: register `AddOutputCache()`, add `UseOutputCache()`, and chain `.CacheOutput()` on the `MapOpenApi()` builder. - If the document should not depend on a running server at all, generate it at build time with `Microsoft.Extensions.ApiDescription.Server` and serve or publish the file. ## Several documents in one app Each `AddOpenApi(name)` call adds a document served at `/openapi/{name}.json`. The default `ShouldInclude` predicate keeps an endpoint when its `ApiDescription.GroupName` is **null** or **equal to the document name**. Endpoints tagged with `WithGroupName("internal")` therefore appear only in the `internal` document, while endpoints with no group name appear in every document. Replace `options.ShouldInclude` when you need a different split. ## Coming from a .NET 8 project A .NET 8 `webapi` project typically contains `AddEndpointsApiExplorer()`, `AddSwaggerGen()`, `UseSwagger()` and `UseSwaggerUI()`. Moving to the built-in generator replaces the first three with `AddOpenApi()` and `MapOpenApi()`, and the **URL changes** from `/swagger/v1/swagger.json` to `/openapi/v1.json`. Anything that pointed at the old URL has to follow: - a Swagger UI or Scalar configuration, - a client generator or contract test that downloads the document, - a gateway or portal that imports it. Keeping both generators running side by side for long produces two documents that drift apart, so pick one. ## What is not included - **No UI.** The package produces a document; rendering it is another package's job. - **No client generation.** Generators consume the document; they are separate tools. - **No Swashbuckle types.** `AddSwaggerGen`, `UseSwagger` and `UseSwaggerUI` belong to Swashbuckle and are unrelated to `AddOpenApi`.

  • How do you expose the document in Production without regenerating it on every request?
    Call `app.MapOpenApi()` outside the `IsDevelopment()` check, register `AddOutputCache()` and `UseOutputCache()`, and chain `.CacheOutput()` on the `MapOpenApi()` builder so the JSON is served from the output cache. If the document must not depend on the running app at all, generate it at build time with `Microsoft.Extensions.ApiDescription.Server` and publish the file instead.
  • What does a request to /openapi/v2.json return when only AddOpenApi() was called?
    The `MapOpenApi` endpoint looks up a keyed document service by the lower-cased name, finds none and answers 404 with a plain-text message that no OpenAPI document with that name was found. Because names are lower-cased on both sides, `/openapi/V1.json` still resolves the `v1` document.
  • Which endpoints does a second document registered with AddOpenApi("internal") contain?
    The default `ShouldInclude` keeps descriptions whose `GroupName` is null or equals the document name. Endpoints marked `WithGroupName("internal")` land only in that document, and ungrouped endpoints land in both. Set `options.ShouldInclude` to change the split.

  • The .NET 10 webapi template still references Swashbuckle.AspNetCore and calls AddSwaggerGen.
  • MapOpenApi also serves an interactive Swagger UI page at /swagger.
  • AddEndpointsApiExplorer must be called before AddOpenApi or Minimal API endpoints go missing.
  • The template's MapOpenApi call exposes the document in every environment, Production included.
  • In .NET 10 the built-in generator still writes OpenAPI 3.0 unless you opt in to 3.1.

Assumes ASP.NET Core 10: Microsoft.AspNetCore.OpenApi in the webapi template since .NET 9, Swashbuckle removed from templates in 9, and OpenAPI 3.1 as the default document version in 10.