Deprecate `WithOpenApi` extension methods

[captainsafia]

Summary

This issue proposes deprecating the WithOpenApi extension methods in Microsoft.AspNetCore.OpenApi with diagnostic code ASPDEPR002. This represents a revision to the decision outlined in domaindrivendev/Swashbuckle.AspNetCore#2849. Upon further evaluation and discussion with @martincostello, obsoleting these APIs in .NET 10 would provide a better experience for users given the current set of tools in the OpenAPI space.

Background

In .NET 7, we introduced the WithOpenApi endpoint extension methods for minimal APIs. These methods generate an OpenApiOperation associated with the endpoint and insert it into endpoint metadata for consumption by Swashbuckle.AspNetCore.

With the introduction of built-in OpenAPI document generation in Microsoft.AspNetCore.OpenApi, we initially considered several options for the future of WithOpenApi (as discussed in the referenced Swashbuckle issue). After further consideration, we have decided that the best path forward is to deprecate these methods in favor of more distinct OpenAPI features in M.A.OpenApi and Swashbuckle.

Proposed Changes

Mark the following methods as [Obsolete] with diagnostic code ASPDEPR002:

1. WithOpenApi<TBuilder>(this TBuilder builder)
2. WithOpenApi<TBuilder>(this TBuilder builder, Func<OpenApiOperation, OpenApiOperation> configureOperation)

Obsoletion message:

"WithOpenApi is deprecated and will be removed in a future release. For more information, visit https://aka.ms/aspnet/deprecate/002."

Migration Path

Users should migrate from WithOpenApi() to either the built-in OpenAPI document generation or the OperationFilter feature supported by Swashbuckle.