|
| 1 | +--- |
| 2 | +title: "IncludeOpenAPIAnalyzers property and MVC API analyzers are deprecated" |
| 3 | +description: "Learn about the breaking change in ASP.NET Core 10 where the IncludeOpenAPIAnalyzers property and its associated MVC API analyzers are deprecated." |
| 4 | +ms.date: 08/07/2025 |
| 5 | +ai-usage: ai-assisted |
| 6 | +ms.custom: https://github.com/aspnet/Announcements/issues/521 |
| 7 | +--- |
| 8 | + |
| 9 | +# IncludeOpenAPIAnalyzers property and MVC API analyzers are deprecated |
| 10 | + |
| 11 | +The `IncludeOpenAPIAnalyzers` MSBuild property and its associated MVC API analyzers are deprecated and will be removed in a future release. When `IncludeOpenAPIAnalyzers` is set to `true`, the build now emits warning `ASPDEPR007`. |
| 12 | + |
| 13 | +## Version introduced |
| 14 | + |
| 15 | +.NET 10 Preview 7 |
| 16 | + |
| 17 | +## Previous behavior |
| 18 | + |
| 19 | +Previously, developers could set `<IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>` in their Web SDK projects to enable MVC API analyzers without any warnings or deprecation notices. |
| 20 | + |
| 21 | +```xml |
| 22 | +<Project Sdk="Microsoft.NET.Sdk.Web"> |
| 23 | + <PropertyGroup> |
| 24 | + <TargetFramework>net9.0</TargetFramework> |
| 25 | + <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> |
| 26 | + </PropertyGroup> |
| 27 | +</Project> |
| 28 | +``` |
| 29 | + |
| 30 | +Such a project built successfully without any deprecation warnings. |
| 31 | + |
| 32 | +## New behavior |
| 33 | + |
| 34 | +Starting in .NET 10, when `IncludeOpenAPIAnalyzers` is set to `true`, the build emits warning `ASPDEPR007`: |
| 35 | + |
| 36 | +> warning ASPDEPR007: The IncludeOpenAPIAnalyzers property and its associated MVC API analyzers are deprecated and will be removed in a future release. |
| 37 | +
|
| 38 | +The analyzers continue to function, but developers receive this deprecation warning during compilation. |
| 39 | + |
| 40 | +## Type of breaking change |
| 41 | + |
| 42 | +This change can affect [source compatibility](../../categories.md#source-compatibility). |
| 43 | + |
| 44 | +## Reason for change |
| 45 | + |
| 46 | +The MVC API analyzers were originally introduced to help keep return types and attributes in sync for API controllers, ensuring consistency between method signatures and their corresponding OpenAPI documentation. These analyzers provided compile-time validation to catch mismatches between declared return types and the actual types returned by controller actions. |
| 47 | + |
| 48 | +However, with the introduction of Minimal APIs and the <xref:Microsoft.AspNetCore.Http.TypedResults> pattern, the .NET ecosystem has evolved toward a more type-safe approach for API development. `TypedResults` provides compile-time guarantees about response types without requiring additional analyzers, making the MVC API analyzers redundant for modern .NET applications. In .NET 10, `TypedResults` are supported in controller-based APIs. |
| 49 | + |
| 50 | +Previous approach with MVC API analyzers: |
| 51 | + |
| 52 | +```csharp |
| 53 | +[HttpGet] |
| 54 | +[ProducesResponseType<Product>(200)] |
| 55 | +[ProducesResponseType(404)] |
| 56 | +public async Task<ActionResult> GetProduct(int id) |
| 57 | +{ |
| 58 | + var product = await _productService.GetByIdAsync(id); |
| 59 | + if (product == null) |
| 60 | + return NotFound(); // Analyzer ensures this matches ProducesResponseType(404) |
| 61 | +
|
| 62 | + return Ok(product); // Analyzer ensures this matches ProducesResponseType<Product>(200) |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +Modern approach with `TypedResults`: |
| 67 | + |
| 68 | +```csharp |
| 69 | +[HttpGet("{id}")] |
| 70 | +public async Task<Results<Ok<Product>, NotFound>> GetProduct(int id) |
| 71 | +{ |
| 72 | + var product = await _productService.GetByIdAsync(id); |
| 73 | + return product == null |
| 74 | + ? TypedResults.NotFound() |
| 75 | + : TypedResults.Ok(product); |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +The `TypedResults` pattern eliminates the need for separate analyzers because the return type itself (`Results<Ok<Product>, NotFound>`) explicitly declares all possible response types at compile time. This approach is more maintainable, provides better IntelliSense support, and automatically generates accurate OpenAPI documentation without additional tooling. |
| 80 | + |
| 81 | +As the .NET ecosystem continues to embrace `TypedResults` as the recommended pattern for API development, the MVC API analyzers have become obsolete and are being deprecated to streamline the development experience. |
| 82 | + |
| 83 | +## Recommended action |
| 84 | + |
| 85 | +Developers should: |
| 86 | + |
| 87 | +- Remove the deprecated property: Remove `<IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>` from your project files to eliminate the warning. |
| 88 | +- Migrate to `TypedResults`: Migrate to the `TypedResults` pattern to ensure better consistency between application behavior and OpenAPI documentation. |
| 89 | + |
| 90 | +If you need to continue using the deprecated analyzers temporarily, you can suppress the warning: |
| 91 | + |
| 92 | +```xml |
| 93 | +<PropertyGroup> |
| 94 | + <NoWarn>$(NoWarn);ASPDEPR007</NoWarn> |
| 95 | +</PropertyGroup> |
| 96 | +``` |
| 97 | + |
| 98 | +## Affected APIs |
| 99 | + |
| 100 | +- MSBuild property: `IncludeOpenAPIAnalyzers`. |
| 101 | +- Associated MVC API analyzers included when `IncludeOpenAPIAnalyzers` is `true`. |
0 commit comments