Merge to Live

aspnetcore/breaking-changes/10/withopenapi-deprecated.md

@@ -8,7 +8,7 @@ ms.custom: https://github.com/aspnet/Announcements/issues/519
 
 # Deprecation of WithOpenApi extension method
 
-The <xref:Microsoft.AspNetCore.Builder.OpenApiEndpointConventionBuilderExtensions.WithOpenApi*> methods have been deprecated in .NET 10. Invoking these methods now produces the compile-time diagnostic `ASPDEPR002` and a standard `Obsolete` warning that states:
+The <xref:Microsoft.AspNetCore.Builder.OpenApiEndpointConventionBuilderExtensions.WithOpenApi*> methods have been deprecated in .NET 10. Invoking these methods now produces the compile-time diagnostic [`ASPDEPR002`](xref:diagnostics/aspdepr002) and a standard `Obsolete` warning that states:
 
 > WithOpenApi is deprecated and will be removed in a future release. For more information, visit <https://aka.ms/aspnet/deprecate/002>.
 

aspnetcore/diagnostics/aspdepr-ids.md

@@ -0,0 +1,26 @@
+---
+title: ASPDEPR diagnostics overview
+ai-usage: ai-assisted
+author: tdykstra
+description: Overview of ASPDEPR deprecation diagnostics in ASP.NET Core.
+monikerRange: '>= aspnetcore-10.0'
+ms.author: tdykstra
+ms.date: 03/03/2026
+uid: diagnostics/aspdepr-ids
+---
+# ASPDEPR diagnostics overview
+
+ASPDEPR diagnostics are compile-time warnings issued by the .NET compiler when your code uses ASP.NET Core APIs that have been deprecated. Deprecated APIs are still functional but are scheduled for removal in a future release. Addressing these warnings helps keep your code up to date and ensures a smoother upgrade path.
+
+ASPDEPR diagnostics are similar to the [`SYSLIB` obsoletions](/dotnet/fundamentals/syslib-diagnostics/obsoletions-overview) in .NET, but are specific to ASP.NET Core.
+
+> [!NOTE]
+> This article is a work-in-progress. It's not a complete list of deprecation diagnostics.
+
+## ASPDEPR diagnostics
+
+The following table lists the `ASPDEPR` deprecation diagnostics for ASP.NET Core:
+
+| Diagnostic ID                             | Description                 |
+|-------------------------------------------|-----------------------------|
+| [ASPDEPR002](xref:diagnostics/aspdepr002) | `WithOpenApi` is deprecated |

aspnetcore/diagnostics/aspdepr002.md

@@ -0,0 +1,96 @@
+---
+title: ASPDEPR002 warning
+description: Learn about the obsoletions that generate compile-time warning ASPDEPR002.
+ai-usage: ai-assisted
+monikerRange: '>= aspnetcore-10.0'
+ms.date: 03/03/2026
+uid: diagnostics/aspdepr002
+ms.author: tdykstra
+author: tdykstra
+f1_keywords:
+  - aspdepr002
+---
+# ASPDEPR002: `WithOpenApi` is deprecated
+
+The <xref:Microsoft.AspNetCore.Builder.OpenApiEndpointConventionBuilderExtensions.WithOpenApi*> extension methods are deprecated starting in .NET 10. Using these methods produces the `ASPDEPR002` diagnostic at compile time. The functionality they provided is now available through the built-in OpenAPI document generation pipeline.
+
+## Workarounds
+
+Remove `.WithOpenApi()` calls from your code.
+
+- If you used `Microsoft.AspNetCore.OpenApi` for document generation, use the `AddOpenApiOperationTransformer` extension method instead.
+
+  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 you used `Swashbuckle` for document generation, use the `IOperationFilter` API.
+- If you used `NSwag` for document generation, use the `IOperationProcessor` API.
+
+## Suppress a warning
+
+If you must use the deprecated APIs, you can suppress the warning in code or in your project file.
+
+To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning.
+
+```csharp
+// Disable the warning.
+#pragma warning disable ASPDEPR002
+
+// Code that uses deprecated API.
+// ...
+
+// Re-enable the warning.
+#pragma warning restore ASPDEPR002
+```
+
+To suppress all the `ASPDEPR002` warnings in your project, add a `<NoWarn>` property to your project file.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+   ...
+   <NoWarn>$(NoWarn);ASPDEPR002</NoWarn>
+  </PropertyGroup>
+</Project>
+```
+
+## See also
+
+- [Deprecation of WithOpenApi extension method](../breaking-changes/10/withopenapi-deprecated.md)

aspnetcore/toc.yml

@@ -1652,8 +1652,10 @@ items:
       - name: Azure and IIS errors reference
         uid: host-and-deploy/azure-iis-errors-reference
   - name: Code analysis
-    uid: diagnostics/code-analysis
     items:
+      - name: Overview
+        displayName: code analysis
+        uid: diagnostics/code-analysis
       - name: ASP0000
         uid: diagnostics/asp0000
       - name: ASP0001
@@ -1740,8 +1742,10 @@ items:
         uid: diagnostics/mvc1005
       - name: MVC1006
         uid: diagnostics/mvc1006
-      - name: RDG diagnostics
-        displayName: aot, RDG diagnostics
+  - name: RDG diagnostics
+    items:
+      - name: Overview
+        displayName: aot, rdg diagnostics
         uid: fundamentals/aot/request-delegate-generator/rdg-ids
       - name: RDG002
         uid: fundamentals/aot/request-delegate-generator/diagnostics/rdg002
@@ -1765,6 +1769,13 @@ items:
         uid: fundamentals/aot/request-delegate-generator/diagnostics/rdg012
       - name: RDG013
         uid: fundamentals/aot/request-delegate-generator/diagnostics/rdg013
+  - name: ASPDEPR diagnostics
+    items:
+      - name: Overview
+        displayName: aspdepr diagnostics
+        uid: diagnostics/aspdepr-ids
+      - name: ASPDEPR002
+        uid: diagnostics/aspdepr002
   - name: Data access
     items:
       - name: Tutorials