[Breaking change]: IncludeOpenAPIAnalyzers property and MVC API analyzers are deprecated

[captainsafia]

Description

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 will now emit warning ASPDEPR007.

Version

.NET 10 Preview 7

Previous behavior

Previously, developers could set <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> in their Web SDK projects to enable MVC API analyzers without any warnings or deprecation notices.

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
  </PropertyGroup>
</Project>

The project would build successfully without any deprecation warnings.

New behavior

Starting in .NET 10 Preview 7, when IncludeOpenAPIAnalyzers is set to true, the build will emit warning ASPDEPR007:

warning ASPDEPR007: The IncludeOpenAPIAnalyzers property and its associated MVC API analyzers are deprecated and will be removed in a future release.

The analyzers will continue to function, but developers will receive this deprecation warning during compilation.

Type of breaking change

• Behavioral change: Existing binaries may behave differently at run time.

Reason for change

Reason for change

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.

However, with the introduction of Minimal APIs and the 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.

Previous approach with MVC API analyzers:

[HttpGet]
[ProducesResponseType<Product>(200)]
[ProducesResponseType(404)]
public async Task<ActionResult> GetProduct(int id)
{
    var product = await _productService.GetByIdAsync(id);
    if (product == null)
        return NotFound(); // Analyzer ensures this matches ProducesResponseType(404)
    
    return Ok(product); // Analyzer ensures this matches ProducesResponseType<Product>(200)
}

Or with controller actions using TypedResults:

[HttpGet("{id}")]
public async Task<Results<Ok<Product>, NotFound>> GetProduct(int id)
{
    var product = await _productService.GetByIdAsync(id);
    return product == null 
        ? TypedResults.NotFound() 
        : TypedResults.Ok(product);
}

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.

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.

Recommended action

Developers should:

1. Remove the deprecated property: Remove <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> from your project files to eliminate the warning.

2. Suppress the warning temporarily: If you need to continue using the deprecated analyzers temporarily, you can suppress the warning:

<PropertyGroup>
  <NoWarn>$(NoWarn);ASPDEPR007</NoWarn>
</PropertyGroup>

3. Migrate to TypedResults: Migrate to the TypedResults pattern documented above to ensure better consistency between application behavior and OpenAPI documentation.

Affected APIs

• MSBuild property: IncludeOpenAPIAnalyzers
• Associated MVC API analyzers included when IncludeOpenAPIAnalyzers is true