The .NET 10 version of this page contains examples for .NET 9

[mikekistler]

Description

When viewing the .NET 10 version of this page

some of the examples are still using .NET 9

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview?view=aspnetcore-10.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/overview.md

Document ID

d8ac1ac3-8b34-6886-bca4-740514f94229

Platform Id

fc9e39cd-d174-e15e-47f9-bedd1b2be2cd

Article author

@wadepickett

Metadata

• ID: d8ac1ac3-8b34-6886-bca4-740514f94229
• PlatformId: fc9e39cd-d174-e15e-47f9-bedd1b2be2cd
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues

[wadepickett]

Thanks @mikekistler for pointing this out. I need to get it fixed.

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution or answer to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution!

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-03-20
Issue: 36903
Model: GitHub Copilot

---

Issue Analysis: .NET 10 OpenAPI Overview Page References .NET 9 Samples

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The .NET 10 version of the OpenAPI overview page (aspnetcore/fundamentals/openapi/overview.md) references code samples from the 9.x sample folder instead of the 10.x sample folder. The moniker range >= aspnetcore-9.0 covers both .NET 9 and .NET 10 views, but the code-include directives on lines 29, 47, and 60 all point to ~/fundamentals/openapi/samples/9.x/WebMinOpenApi/... files. A complete .NET 10 sample project already exists at aspnetcore/fundamentals/openapi/samples/10.x/WebMinOpenApi/ with the correct net10.0 target framework and 10.0.*-* package versions, but the overview.md article does not reference it.

Other OpenAPI articles in the same folder (e.g., customize-openapi.md, include-metadata.md) already reference the 10.x samples for their .NET 10 moniker range, confirming that the 10.x samples are intended to be used.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/fundamentals/openapi/overview.md	14-75	:::moniker range=">= aspnetcore-9.0" block
9.x Program.cs (current ref)	aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs	—	snippet_default
9.x projectFile.xml (current ref)	aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml	—	net9.0 TFM, 9.0.*-* packages
10.x Program.cs (correct ref)	aspnetcore/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs	—	snippet_default
10.x projectFile.xml (correct ref)	aspnetcore/fundamentals/openapi/samples/10.x/WebMinOpenApi/projectFile.xml	—	net10.0 TFM, 10.0.*-* packages

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential Documentation Updates

The root cause is that the moniker range >= aspnetcore-9.0 covers both .NET 9 and .NET 10 without version-split monikers, and all three code-include references point to 9.x samples. The fix requires either:

Option A (Preferred): Split moniker ranges to serve version-appropriate samples:

File: aspnetcore/fundamentals/openapi/overview.md
Location: Lines 14-75
Type: Replacement — split single moniker block into two version-specific blocks

Current content (lines 14, 29, 47, 60):

:::moniker range=">= aspnetcore-9.0"
...
[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_default&highlight=5,9-12)]
...
[!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=15)]
...
[!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=9-12,16-19)]
...
:::moniker-end

Suggested direction:

:::moniker range=">= aspnetcore-10.0"
...
[!code-csharp[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs?name=snippet_default&highlight=5,9-12)]
...
[!code-xml[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/projectFile.xml?highlight=15)]
...
[!code-xml[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/projectFile.xml?highlight=9-12,16-19)]
...
:::moniker-end

:::moniker range="aspnetcore-9.0"
...
[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_default&highlight=5,9-12)]
...
[!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=15)]
...
[!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=9-12,16-19)]
...
:::moniker-end

Option B (Simpler but less precise): If the .NET 9 and .NET 10 content is identical except for version numbers, update all three references within the existing >= aspnetcore-9.0 moniker to point to the 10.x samples (since 10.x is the latest). This would show net10.0 for both .NET 9 and .NET 10 viewers though, which may not be ideal.

Key Evidence: 10.x samples already exist and are correct

9.x projectFile.xml shows:

<TargetFramework>net9.0</TargetFramework>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />

10.x projectFile.xml shows:

<TargetFramework>net10.0</TargetFramework>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.*-*" />

🎯 Suggested Action Plan

For documentation team review

1. Review file: aspnetcore/fundamentals/openapi/overview.md

   • Navigate to: Line 14 — moniker range start
   • Navigate to: Line 29 — Program.cs code-include (9.x)
   • Navigate to: Line 47 — projectFile.xml code-include (9.x)
   • Navigate to: Line 60 — projectFile.xml code-include (9.x)
   • Consider: Split moniker range into >= aspnetcore-10.0 and aspnetcore-9.0

2. Verify 10.x samples are complete: aspnetcore/fundamentals/openapi/samples/10.x/WebMinOpenApi/

   • Confirm Program.cs has the snippet_default named region
   • Confirm projectFile.xml has the expected highlighted lines

3. Use other articles as a pattern: customize-openapi.md already references 10.x samples for .NET 10 content — follow the same moniker-split pattern.

⚠️ Review Considerations

• Verify that the .NET 10 Program.cs snippet_default region matches the same snippet name and structure used in the 9.x version
• Check if similar 9.x references exist in the included file ~/fundamentals/openapi/includes/overview6-8.md (line 77) — though this file covers older versions, ensure no cross-contamination
• Check the api_endpoint_operation.md include (line 63) for any version-specific sample references
• Consider whether the non-code text within the moniker block needs any .NET 10-specific updates

🔗 References

• Published article: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview?view=aspnetcore-10.0
• Content source: overview.md
• Related issues: Search by Document ID
• 10.x sample project: WebMinOpenApi (10.x)
• Example of correct pattern: customize-openapi.md references to 10.x