Document WithOpenApi deprecation breaking change for .NET 10 Preview 7

Co-authored-by: gewarren <[email protected]>

Author: Copilot

docs/core/compatibility/10.0.md

@@ -15,6 +15,12 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 > [!NOTE]
 > This article is a work in progress. It's not a complete list of breaking changes in .NET 10.
 
+## ASP.NET Core
+
+| Title | Type of change    | Introduced version |
+|-------|-------------------|--------------------|
+| [Deprecation of WithOpenApi extension method](aspnet-core/10.0/withopenapi-deprecated.md) | Behavioral change | Preview 7 |
+
 ## Containers
 
 | Title                                                                          | Type of change    | Introduced version |

docs/core/compatibility/aspnet-core/10.0/withopenapi-deprecated.md

@@ -0,0 +1,96 @@
+---
+title: "Breaking change: Deprecation of WithOpenApi extension method"
+description: "Learn about the breaking change in ASP.NET Core 10 where WithOpenApi extension methods have been deprecated and produce a compiler warning."
+ms.date: 12/17/2024
+ai-usage: ai-assisted
+ms.custom: https://github.com/aspnet/Announcements/issues/519
+---
+
+# Deprecation of WithOpenApi extension method
+
+The `WithOpenApi` extension methods in `Microsoft.AspNetCore.OpenApi.OpenApiEndpointConventionBuilderExtensions` have been deprecated in .NET 10. Invoking these methods now produces the compile-time diagnostic **ASPDEPR002** and a standard `[Obsolete]` warning.
+
+## Version introduced
+
+.NET 10 Preview 7
+
+## Previous behavior
+
+Previously, you could use the `WithOpenApi` extension method without any warnings:
+
+```csharp
+app.MapGet("/weather", () => ...)
+   .WithOpenApi();   // no warnings
+```
+
+## New behavior
+
+Starting in .NET 10 Preview 7, using the `WithOpenApi` extension method produces a compiler warning:
+
+```csharp
+app.MapGet("/weather", () => ...)
+   .WithOpenApi();   // warning ASPDEPR002: WithOpenApi is deprecated and will be removed in a future release. For more information, visit https://aka.ms/aspnet/deprecate/002.
+```
+
+The call still compiles and executes, but the build now emits the new deprecation warning.
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+`WithOpenApi` duplicated functionality now provided by the built-in OpenAPI document generation pipeline. Deprecating it simplifies the API surface and prepares for its eventual removal.
+
+## Recommended action
+
+Remove `.WithOpenApi()` calls from your code.
+
+- If using `Microsoft.AspNetCore.OpenApi` for document generation, use the `AddOpenApiOperationTransformer` extension method.
+
+**Before**
+
+```csharp
+using Microsoft.AspNetCore.OpenApi;
+
+var builder = WebApplication.CreateBuilder();
+var app = builder.Build();
+
+app.MapGet("/weather", () => ...)
+   .WithOpenApi(operation =>
+   {
+       // Per-endpoint tweaks
+       operation.Summary     = "Gets the current weather report.";
+       operation.Description = "Returns a short description and emoji.";
+       return operation;
+   });
+
+app.Run();
+```
+
+**After**
+
+```csharp
+using Microsoft.AspNetCore.OpenApi;
+
+var builder = WebApplication.CreateBuilder();
+var app = builder.Build();
+
+app.MapGet("/weather", () => ...)
+   .AddOpenApiOperationTransformer((operation, context, ct) =>
+   {
+       // Per-endpoint tweaks
+       operation.Summary     = "Gets the current weather report.";
+       operation.Description = "Returns a short description and emoji.";
+       return Task.CompletedTask;
+   });
+
+app.Run();
+```
+
+- If using `Swashbuckle` for document generation, use the `IOperationFilter` API.
+- If using `NSwag` for document generation, use the `IOperationProcessor` API.
+
+## Affected APIs
+
+- <xref:Microsoft.AspNetCore.OpenApi.OpenApiEndpointConventionBuilderExtensions.WithOpenApi%2A?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -8,6 +8,10 @@ items:
         items:
           - name: Overview
             href: 10.0.md
+          - name: ASP.NET Core
+            items:
+              - name: Deprecation of WithOpenApi extension method
+                href: aspnet-core/10.0/withopenapi-deprecated.md
           - name: Containers
             items:
               - name: Default .NET images use Ubuntu