skip to content

OpenAPI Documents

AddOpenApi and MapOpenApi build OpenAPI 3.1 documents from endpoint metadata, shaped by transformers; Swashbuckle left the templates in .NET 9. Interviewers ask how metadata reaches the spec.

part ofASP.NET Coreread it →
on this pageshow

explore

questions

6

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.

open as a page

In ASP.NET Core 10, how does endpoint metadata such as WithName, WithSummary and Produces reach the generated OpenAPI document?

level: middleimportance: must knowfreq 55%

basics

~20 s

The generator never reads handler bodies: ApiExplorer turns each endpoint's metadata into an ApiDescription, and the OpenAPI service maps it, WithName to operationId, WithSummary and WithDescription to summary and description, Produces and [ProducesResponseType] to responses.

open as a page

In a .NET 10 ASP.NET Core API, when would you keep Swashbuckle or NSwag instead of the built-in Microsoft.AspNetCore.OpenApi generator?

level: middleimportance: should knowfreq 50%

basics

~20 s

New .NET 10 APIs normally use Microsoft.AspNetCore.OpenApi. Keep Swashbuckle when an existing app relies on its filters, annotations, CLI or Swagger 2.0 output, and NSwag when you also want its C# or TypeScript client generation from the same toolchain.

open as a page

In ASP.NET Core 10, how would you use OpenAPI transformers to add a JWT bearer security scheme to a public flight-status API's document?

level: middleimportance: should knowfreq 45%

basics

~10 s

Register an IOpenApiDocumentTransformer with options.AddDocumentTransformer<T>() inside AddOpenApi. It adds an http bearer scheme to document.Components.SecuritySchemes; an operation transformer then adds a requirement referencing it to every endpoint that is not anonymous.

open as a page

When you upgrade an ASP.NET Core 9 API with custom OpenAPI transformers to .NET 10, what changes in the generated document and what breaks?

level: seniorimportance: should knowfreq 35%

basics

~20 s

ASP.NET Core 10 emits OpenAPI 3.1 by default and builds on Microsoft.OpenApi 2, so transformers using Nullable, OpenApiAny, string schema types or Reference objects must be rewritten, even if OpenApiVersion is set back to OpenApi3_0.

open as a page

In ASP.NET Core 10, how does build-time OpenAPI document generation work, and what can go wrong when it runs your Program.cs?

level: seniorimportance: nice to knowfreq 22%

basics

~20 s

Adding Microsoft.Extensions.ApiDescription.Server makes every build run the app's entry point under a mock server, ask the registered generator for each document and write {ProjectName}.json to obj by default; startup code that needs real infrastructure must be guarded.

open as a page