OpenAPI: Marking Operations, Schemas and Properties as deprecated based on the [Obsolete] attribute

[desjoerd]

Summary

There are a couple of issues around deprecating operations in the openapi or api explorer based on some specific metadata. A proposal would be to just let it be metadata of type ObsoleteAttribute which can be applied to endpoints and schemas.

Related issues:

• OpenApi ApiVersionAttribute.Deprecated not reflected in schema #57853
• Support Deprecation Metadata in the API Explorer #43493

Motivation and goals

In the current situation you cannot mark operations, schemas and properties as deprecated. It should be possible to do that. In .NET we've got the Obsolete Attribute which is used to mark properties, methods and classes as deprecated and this should be reflected in the generated OpenApi.

For endpoints we got both MVC Controllers and Minimal Api's. With MVC Controllers the Obsolete attribute can be applied directly to a controller or action which would add this to the endpoint metadata.
For minimal api's it can be added with .WithMetadata(new ObsoleteAttribute) or on the method itself.
For schemas it can be applied to the class or to the properties.

In scope

The following should be able to be marked as deprecated in the generated OpenApi:

• MVC Controllers and Actions
• Minimal api endpoints
• Schemas & properties

It should also provide guidance to for example https://github.com/dotnet/aspnet-api-versioning to add the ObsoleteAttribute as metadata to deprecated apis.

Out of scope

• Handling other types of attributes/metadata
• Updating the Api Explorer (only metadata)

Risks / unknowns

The ObsoleteAttribute will emit warnings when applied on targets. That it's marked as Obsolete doesn't mean it's out of support. Users could be tempted to ignore/disable this error on a global level.