v11 update: OpenAPI document generation — HTTP QUERY support and the default 3.2 document version #37701

Target repository: dotnet/AspNetCore.Docs
Analyzed at commit: 4986136881f2bbf1879f10106467769df5a49932
Product source verified at: dotnet/aspnetcore @ 1fcd7ef305697a1888f3ede076010350ae9f4f8d
Source release notes: HTTP QUERY in generated OpenAPI documents; OpenAPI 3.2 by default; Select an environment for build-time OpenAPI document generation

🎯 Goal

The docset currently tells .NET 11 readers the exact opposite of what .NET 11 does, and the statement is not behind a .NET 10 moniker. fundamentals/openapi/aspnetcore-openapi.md L77 states that QUERY is gracefully excluded from generated OpenAPI documents. That line sits inside :::moniker range=">= aspnetcore-10.0" (opens L13, closes L297), so it renders for .NET 11 readers and names the one method this release added support for as the example of a method that gets dropped.

Product source at the pinned commit disagrees on both counts: ApiDescriptionExtensions.cs L43 maps "QUERY" => HttpMethod.Query, and L44 falls through to TryCreateHttpMethod(normalizedHttpMethod), so any syntactically valid HTTP method token now produces an operation. Only a missing or malformed token is skipped, at OpenApiDocumentService.cs L298–L301. Beyond correcting the sentence, the query Path Item field, additionalOperations, x-oai-additionalOperations, and a worked MapMethods example have zero coverage outside the release notes.

The weaker residual finding is that the section titled Customize the OpenAPI version of a generated document never names the new default in its opening sentence and demos OpenApi3_0. The default-version change is otherwise well covered: aspnetcore-openapi.md L25 states the .NET 11 default is OpenAPI 3.2 and the .NET 10 default is 3.1, and the breaking-change article is complete.

The build-time environment feature is fully documented, correctly version-scoped, and in the right place. aspnetcore-openapi.md L299–L313 already contains the OpenApiGenerationEnvironment property name, the XML snippet, environment-variable equivalence, and explanation of what selecting the environment affects. This issue records that evidence and explicitly says not to touch that section.

✅ Coverage status summary

Legend: ✅ already documented · ✏️ update needed · 🟣 could not determine

🔢 Version applicability

Applies to: >= aspnetcore-11.0 for the HTTP QUERY and 3.2 default statements; = aspnetcore-10.0 companion variants preserve .NET 10 behavior where needed; build-time environment content is already scoped to >= aspnetcore-11.0.
Target moniker: >= aspnetcore-11.0
Earlier versions affected: .NET 10 behavior must remain intact for both split regions. The build-time environment property doesn't exist before .NET 11.

Zone map of the article as it stands (verified by full read):

⚠️ Moniker state belongs to the insertion point, not to the article as a whole. The article already has an 11.0 zone, but it starts at L299. It cannot be used for content that belongs at L75–L79 or L119–L126 without moving the content roughly 180–220 lines away from the relevant sections.

Authoritative combined moniker balance: the file currently has 3 :::moniker range= openers and 3 :::moniker-end closers. Change 1 adds 3 openers and 3 closers (close the existing zone, add = aspnetcore-10.0, add >= aspnetcore-11.0, then reopen >= aspnetcore-10.0). Change 2 adds the same 3 openers and 3 closers for its independent split. Changes 3 and 4 add none. Therefore the merged edit must end at 3 + 3 + 3 = 9 openers and 3 + 3 + 3 = 9 closers. Any per-change figure stated in isolation below is superseded by this combined 9/9 requirement.

Tab groups: the article contains tab groups at L46–L62, L206–L222, and L231–L245. Neither edit region nor the verified L299–L313 section is inside a tab group, so no moniker directive is placed inside a tab group.

📋 Coverage gap summary

HTTP QUERY: A developer adds app.MapMethods("/search", ["QUERY"], …) to a .NET 11 app and sees a query key or x-oai-additionalOperations entry in the generated document. The current article tells that reader QUERY is excluded, and the docset has no worked example or explanation of OpenAPI 3.2 query, additionalOperations, or 3.0/3.1 x-oai-additionalOperations. Product source shows the behavior is broader than the release note: any valid custom verb is described.

Feature announced in What's New:

OpenAPI document generation now recognizes HTTP QUERY as a known operation type. QUERY is a proposed safe, idempotent method that lets clients send a request body when describing a search, useful when a query is too large or too structured to fit in a URL. Routing already accepts arbitrary verb strings via MapMethods, and OpenAPI 3.2 adds a query field to the Path Item Object so this can be described in the OpenAPI document.

Note that query is only valid in an OpenAPI 3.2 document, so set the OpenApiVersion in the OpenApiOptions. In earlier OpenAPI versions, the query operation is generated within an x-oai-additionalOperations specification extension in the Path Item Object.

Breaking change: Not classified as one, but it is behavior-visible. An app that used a custom verb produced a document without that path in .NET 10 and produces one with it in .NET 11.

OpenAPI 3.2 by default: Someone upgrading to .NET 11 notices 3.2.0, opens the section named Customize the OpenAPI version of a generated document, and reads a tautology plus an OpenApi3_0 sample. The answer exists at L25 and in the breaking-change article, but not in the section a reader navigates to for that question.

Feature announced in What's New:

Generated OpenAPI documents now target OpenAPI 3.2 by default. Documents continue to generate as before. Set the document version explicitly if you need to target an earlier version for tooling that doesn't yet support OpenAPI 3.2.

Breaking change: Yes — behavioral. Already documented and indexed.

Build-time environment: There is no gap. A reader configuring build-time OpenAPI generation sees OpenApiGenerationEnvironment under ### Customize build-time document generation; it names the property, shows the XML, states the environment-variable equivalence, and explains environment-specific configuration and transformers.

Feature announced in What's New:

Build-time OpenAPI document generation supports selecting the app environment with the OpenApiGenerationEnvironment MSBuild property. The property sets the host's environment for the generation process, equivalent to setting the ASPNETCORE_ENVIRONMENT or DOTNET_ENVIRONMENT environment variable.

Breaking change: No. New opt-in MSBuild property; absent, behavior is unchanged.

📁 Affected files

Target article uid: fundamentals/openapi/aspnetcore-openapi

📝 Proposed changes

✏️ 1. Update — aspnetcore/fundamentals/openapi/aspnetcore-openapi.md, correct HTTP-method behavior and add QUERY / custom-method guidance (lines 75–79)

Merged from: the "HTTP QUERY in generated OpenAPI documents" analysis, changes 1 and 2. That analysis treated the behavior-list correction and the new subsection as adjacent sub-changes; this issue applies them as one contiguous replacement so the moniker split is done once.

Applies to: >= aspnetcore-11.0 for the new content; = aspnetcore-10.0 for the preserved original bullet
Moniker handling: State D — full four-directive split. The insertion region is inside :::moniker range=">= aspnetcore-10.0" (L13 → L297), which is broader than the target. The edit closes that zone, opens = aspnetcore-10.0 for the existing text, closes it, opens >= aspnetcore-11.0 for the corrected bullets and the new section, closes it, then reopens >= aspnetcore-10.0 with the range expression reproduced character for character so the remainder of zone 1 still closes at its original :::moniker-end.
Moniker balance: this change alone takes the file from 3 / 3 to 6 / 6. Applied together with change 2, the file must end at 9 / 9 — see the authoritative combined derivation under Version applicability.
Location: Lines 75–79, between the "Launch the app…" paragraph (L73) and ## Options to Customize OpenAPI document generation (L80).

Before (lines 73–80):

Launch the app and navigate to `https://localhost:{PORT}/openapi/v1.json` to view the generated OpenAPI document, where the `{PORT}` placeholder is the port.

OpenAPI document generation applies the following behaviors:

* Unknown HTTP methods are excluded from the generated document. For example, the `QUERY` method is an HTTP method that isn't yet recognized by the OpenAPI specification, so it's gracefully excluded from the generated document.
* Numbers and dates are formatted using the invariant culture, so the generated document is consistent regardless of the server's culture settings.

## Options to Customize OpenAPI document generation

After:

Launch the app and navigate to `https://localhost:{PORT}/openapi/v1.json` to view the generated OpenAPI document, where the `{PORT}` placeholder is the port.

OpenAPI document generation applies the following behaviors:

:::moniker-end

:::moniker range="= aspnetcore-10.0"

* Unknown HTTP methods are excluded from the generated document. For example, the `QUERY` method is an HTTP method that isn't yet recognized by the OpenAPI specification, so it's gracefully excluded from the generated document.
* Numbers and dates are formatted using the invariant culture, so the generated document is consistent regardless of the server's culture settings.

:::moniker-end

:::moniker range=">= aspnetcore-11.0"

* HTTP methods that the OpenAPI specification doesn't define as fixed fields, including `QUERY` and app-defined custom verbs, are described in the generated document. For more information, see [Operations for HTTP QUERY and custom HTTP methods](#operations-for-http-query-and-custom-http-methods).
* Endpoints whose HTTP method is missing or isn't a syntactically valid HTTP method token are excluded from the generated document.
* Numbers and dates are formatted using the invariant culture, so the generated document is consistent regardless of the server's culture settings.

### Operations for HTTP QUERY and custom HTTP methods

Routing accepts arbitrary HTTP method strings through <xref:Microsoft.AspNetCore.Builder.EndpointRouteBuilderExtensions.MapMethods%2A>. Starting in .NET 11, OpenAPI document generation describes those operations instead of omitting them.

[HTTP QUERY](https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/) is a proposed safe, idempotent method that lets a client send a request body when describing a search. It's useful when a query is too large or too structured to fit in a URL. OpenAPI 3.2 defines a [`query` field on the Path Item Object](https://spec.openapis.org/oas/v3.2.0.html#fixed-fields-6) for exactly this case.

The following endpoint uses `MapMethods` to handle `QUERY` requests:

```csharp
app.MapMethods("/search", ["QUERY"], (SearchRequest request) =>
    SearchService.Run(request));
```

In an OpenAPI 3.2 document — the default in .NET 11 — the operation appears inline as a sibling of `get`, `post`, and the other standard operations:

```json
"paths": {
  "/search": {
    "query": {
      "requestBody": { },
      "responses": { "200": { } }
    }
  }
}
```

An HTTP method other than `QUERY` that the OpenAPI specification doesn't define as a fixed field appears under the Path Item's `additionalOperations` field, keyed by the uppercased method name:

```json
"paths": {
  "/purge": {
    "additionalOperations": {
      "PURGE": {
        "responses": { "200": { } }
      }
    }
  }
}
```

In an OpenAPI 3.0 or 3.1 document, neither field exists, so both `QUERY` and other custom methods are emitted under the `x-oai-additionalOperations` specification extension instead:

```json
"paths": {
  "/search": {
    "x-oai-additionalOperations": {
      "QUERY": {
        "requestBody": { },
        "responses": { "200": { } }
      }
    }
  }
}
```

To generate a 3.0 or 3.1 document, set <xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiVersion%2A>. For more information, see [Customize the OpenAPI version of a generated document](#customize-the-openapi-version-of-a-generated-document).

> [!NOTE]
> An endpoint is described only when its HTTP method is a syntactically valid HTTP method token. An endpoint registered with a missing or malformed method string is skipped, and the rest of the document is generated normally.

:::moniker-end

:::moniker range=">= aspnetcore-10.0"

## Options to Customize OpenAPI document generation

Rationale:

• The correction has to be version-split, not overwritten. The existing bullet is accurate for .NET 10 and must keep rendering there. Using = aspnetcore-10.0 for the old text rather than >= aspnetcore-10.0 < aspnetcore-11.0 matches the pattern already used in this docset — for example fundamentals/validation.md L118.
• The invariant-culture bullet is duplicated into both zones on purpose. Splitting a single bulleted list across a zone boundary renders as two separate lists with a gap. Repeating one unchanged bullet is the cheaper defect.
• The new section lives in the article the reader is already in. The question "why is there a query key in my document" arises while reading about document generation, not while reading about metadata attributes. Placing it as a ### under ## Configure OpenAPI document generation keeps it adjacent to the bullet that points at it.
• The section documents the general behavior, not just QUERY. Product source falls through to TryCreateHttpMethod for every unrecognized token, so a QUERY-only section would be accurate and still incomplete.
• It does not repeat the release note's "set the OpenApiVersion" instruction. That advice was written before 3.2 became the default. The section states 3.2 is the default and explains version configuration only for readers who need 3.0 or 3.1 output.

✏️ 2. Update — aspnetcore/fundamentals/openapi/aspnetcore-openapi.md, name the default version (lines 119–126)

Applies to: = aspnetcore-10.0 and >= aspnetcore-11.0
Moniker handling: State D — full split. The insertion region is inside :::moniker range=">= aspnetcore-10.0" (L13 → L297), broader than either target. Close it, emit a = aspnetcore-10.0 variant, close, emit a >= aspnetcore-11.0 variant, close, then reopen >= aspnetcore-10.0 with the range expression reproduced character for character so the rest of zone 1 still closes at its original :::moniker-end on L297.
Moniker balance: in isolation this change takes the file from 3 / 3 to 6 / 6, but it does not land in isolation. Applied after change 1, it takes the file from 6 / 6 to 9 / 9 — see the authoritative combined derivation under Version applicability.
Location: Lines 119–126, the body of the ### Customize the OpenAPI version of a generated document section. The ### heading on L117 is unchanged and stays in zone 1, so the section renders in both builds.

Before (lines 117–127):

### Customize the OpenAPI version of a generated document

By default, OpenAPI document generation creates a document that is compliant with the OpenAPI specification. The following code demonstrates how to modify the default version of the OpenAPI document:

```csharp
builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
});
```

After:

### Customize the OpenAPI version of a generated document

:::moniker-end

:::moniker range="= aspnetcore-10.0"

By default, OpenAPI document generation creates an OpenAPI 3.1 document. The following code demonstrates how to target a different version of the OpenAPI specification:

```csharp
builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
});
```

:::moniker-end

:::moniker range=">= aspnetcore-11.0"

By default, OpenAPI document generation creates an OpenAPI 3.2 document. Target an earlier version when downstream tooling doesn't yet handle OpenAPI 3.2. The following code generates an OpenAPI 3.1 document:

```csharp
builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1;
});
```

For more information about the change of default, see [OpenApiVersion defaults to OpenApi3_2](/aspnet/core/breaking-changes/11/openapi-version-default-3-2).

:::moniker-end

:::moniker range=">= aspnetcore-10.0"

Rationale: Answers the section's own question in its first sentence, for each version. The .NET 11 sample switches from OpenApi3_0 to OpenApi3_1 to match the fallback the breaking-change article recommends — the realistic scenario is tooling that supports 3.1 but not yet 3.2, not tooling stuck on 3.0. The .NET 10 variant keeps OpenApi3_0 unchanged, so nothing that currently renders for .NET 10 readers changes. The pointer to the breaking-change article gives upgraders the migration context without restating it.

✅ 3. No change required — TOC

No TOC change required. aspnetcore-openapi.md and the breaking-change article both already have entries — the latter at toc.yml L44. No new article is proposed.

✅ 4. No change required — aspnetcore/fundamentals/openapi/aspnetcore-openapi.md, "Select the app environment"

The existing content is accurate, complete against every element of the release note, correctly scoped to >= aspnetcore-11.0, and placed alongside the sibling build-time properties. Reproduced here so a reviewer can confirm without opening the file:

Current content (lines 299–313):

:::moniker range=">= aspnetcore-11.0"

#### Select the app environment

Starting in .NET 11, set the `OpenApiGenerationEnvironment` property to select the app environment used during build-time OpenAPI document generation. The property sets the host's environment for the generation process, equivalent to setting the `ASPNETCORE_ENVIRONMENT` or `DOTNET_ENVIRONMENT` environment variable:

```xml
<PropertyGroup>
  <OpenApiGenerationEnvironment>Development</OpenApiGenerationEnvironment>
</PropertyGroup>
```

Selecting the environment enables environment-specific configuration, such as settings from `appsettings.Development.json`, and environment-dependent document transformations to affect the generated document. The property doesn't change the environment used when the app runs normally.

:::moniker-end

✅ Action plan

1. Confirm the already-covered rows first, especially the existing OpenAPI 3.2 default coverage at L25, the breaking-change article, and the build-time environment coverage at L299–L313.
2. Re-read aspnetcore-openapi.md L64–L80 and confirm change 1's Before block matches byte for byte.
3. Apply change 1. Copy :::moniker range=">= aspnetcore-10.0" from L13 verbatim when reopening.
4. Re-derive the location for change 2 after change 1's net +76 line delta, then confirm the enclosing zone is still the reopened >= aspnetcore-10.0 zone.
5. Apply change 2. Keep the ### Customize the OpenAPI version of a generated document heading outside the split so the section title renders in every build.
6. Verify combined zone balance: 9 :::moniker range= and 9 :::moniker-end.
7. Confirm no moniker directive landed inside tab groups L46–L62, L206–L222, or L231–L245.
8. Confirm aspnetcore-openapi.md L299–L313 is unchanged.
9. Build with the .NET 10 moniker. Confirm the original QUERY-excluded bullet still renders, the new QUERY section does not, the OpenAPI-version section names 3.1, and the article still reaches its end.
10. Build with the .NET 11 moniker. Confirm the corrected HTTP-method bullets, the new QUERY section, the 3.2 default sentence/sample, and the build-time environment section render exactly once.
11. Verify the in-page anchors and the site-relative breaking-change link resolve.
12. Resolve any OpenPublishing.Build warnings.

⚠️ Review considerations

• HTTP QUERY: Row 9 is 🟣 because the release note is internally stale, not because the behavior is unclear. The note instructs readers to set options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_2. A later change in the same release made 3.2 the default — see OpenApiOptions.cs L36–L38 and change 2 in this issue. The proposed section deliberately departs from the release note here. If a reviewer prefers to mirror the note exactly, flag it — but the docset already states the default correctly at L25, and copying the note would reintroduce the contradiction.
• HTTP QUERY: The JSON samples use { } where the release note uses { ... }. The release note's literal ... isn't valid JSON. Empty objects keep the samples copy-pasteable and lint-clean while conveying the same shape. If house style prefers the ellipsis, it should at least be inside a comment or the block should be tagged as a fragment.
• HTTP QUERY: additionalOperations vs x-oai-additionalOperations is a real distinction, verified from generated output, not inferred: an OpenAPI 3.2 controllers snapshot emits "additionalOperations" with a "FOO" key (L158–L159) and "query" inline (L129), while the 3.1 and 3.0 snapshots wrap both in "x-oai-additionalOperations" (3.1 L129–L130, L160–L161). Getting this backwards in the docs would be worse than the current silence.
• HTTP QUERY: Consider a sample-code snippet instead of an inline fence. The docset convention in this article is [!code-csharp[](~/fundamentals/openapi/samples/…)]. The MapMethods example is two lines and has no supporting types in the existing sample project, so it's proposed inline. Adding a QUERY endpoint to WebMinOpenApi/Program.cs and referencing it by snippet name would be more consistent with the rest of the article, at the cost of a sample-project change.
• HTTP QUERY: Out of scope for this issue: Server-Sent Events itemSchema support, which is the other OpenAPI 3.2 fixed field added this release (filed separately); the release note's own stale version-setting instruction, which is tracked separately.
• 3.2 by default: This half of the issue is optional. Seven of eight elements are already documented, correctly and in the right places. If the reviewer's judgment is that the L25 statement plus a dedicated breaking-change article is sufficient, dropping change 2 is defensible. The counterargument is that the section titled Customize the OpenAPI version of a generated document should be able to answer "what's the default version" without the reader scrolling 92 lines up.
• 3.2 by default: Changing the sample from OpenApi3_0 to OpenApi3_1 is a judgment call. It's the version the breaking-change article names as the fallback and the version most affected tooling supports. A reviewer who prefers to demonstrate the widest downgrade should keep OpenApi3_0 and only fix the first sentence — the moniker split is still required either way.
• 3.2 by default: Ordering within this issue matters. Change 1 splits the same zone at L75–L79 and lands first, so change 2's line numbers shift by the net +76 lines change 1 introduces, and its starting opener/closer balance is 6 / 6 rather than 3 / 3. This is why the two edits are in one issue rather than two.
• 3.2 by default: Related but separate: the release note for OpenAPI 3.2.0 support still instructs readers to set OpenApiVersion = OpenApi3_2 explicitly, and the HTTP QUERY section repeats that instruction. Both predate this change and are now unnecessary. That's a release-note sequencing artifact, tracked separately — the docset is already correct and needs no edit for it.
• 3.2 by default: Out of scope for this issue: the Microsoft.OpenApi 3.x library upgrade and the Server-Sent Events itemSchema field, both filed separately.
• Build-time environment: One non-blocking imprecision, and it's in the release note, not the docset. The What's New section closes with <xref:fundamentals/openapi/aspnetcore-openapi#customize-build-time-document-generation>, which lands on the parent ### section at L263 rather than the precise #select-the-app-environment anchor at L301. The link resolves and the content is a few lines below, so nothing is broken. If the release note is being touched for other reasons, tightening the anchor is a free improvement. It is not a reason to file a docs issue on its own.
• Build-time environment: The docset says more than the release note, and that's fine. L311's mention of appsettings.Development.json and its "doesn't change the environment used when the app runs normally" clarification have no counterpart in the release note. Both were checked and are consistent with .targets L62, where the environment is passed only to the generation invocation. Don't "correct" the article toward the release note's shorter wording.
• Build-time environment: This section's line numbers shift when the other two changes land. Changes 1 and 2 both split zone 1 (>= aspnetcore-10.0, L13 → L297). Neither touches zone 2, but both move L299–L313 down the file. Re-derive those line numbers from the file rather than trusting the numbers here.
• Build-time environment: Out of scope for this issue: other build-time generation properties, which are already documented at L263–L295, and the mock-server behavior of build-time generation at L317 and following.

🔗 References

• What's New section: HTTP QUERY in generated OpenAPI documents
• The incorrect statement: aspnetcore-openapi.md L77
• Product source — method mapping, including the "QUERY" case and the fall-through that admits any valid token: ApiDescriptionExtensions.cs L23–L57
• Product source — the only remaining exclusion path, for a null/invalid method: OpenApiDocumentService.cs L296–L302
• Generated-output evidence, OpenAPI 3.2: …OpenApi3_2/…documentName=controllers.verified.txt
• Generated-output evidence, OpenAPI 3.1: …OpenApi3_1/…documentName=controllers.verified.txt
• Implementing PRs: dotnet/aspnetcore#65714 (adds the "QUERY" case) and dotnet/aspnetcore#67007 (adds additionalOperations emission and the general fall-through)
• Specification: OpenAPI 3.2.0 Path Item Object fixed fields · HTTP QUERY draft
• What's New section: OpenAPI 3.2 by default
• Existing coverage: aspnetcore-openapi.md L25–L34
• Existing breaking-change article: breaking-changes/11/openapi-version-default-3-2.md
• Breaking-changes index entry: breaking-changes/11/overview.md L31
• Edit target: aspnetcore-openapi.md L117–L126
• Product source — the default value: OpenApiOptions.cs L33–L38
• Implementing PR: dotnet/aspnetcore#67097 — "Update default OpenApi version to 3.2"
• What's New section: Select an environment for build-time OpenAPI document generation
• Existing coverage: aspnetcore-openapi.md L299–L313
• Sibling build-time properties: aspnetcore-openapi.md L263–L295
• Product source — property declaration: Microsoft.Extensions.ApiDescription.Server.props L36–L40
• Product source — the value forwarded to the generator: Microsoft.Extensions.ApiDescription.Server.targets L62
• Community contribution credited in the release note: @ldsenow