Map [Obsolete] attribute to deprecated in OpenAPI documents

[fickleEfrit]

Map [Obsolete] attribute to deprecated in OpenAPI documents

• You've read the Contributor Guide and Code of Conduct.
• You've included unit or integration tests for your change, where applicable.
• You've included inline docs for your change, where applicable.
• There's an open issue for the PR that you are making. If you'd like to propose a new feature or change, please open an issue to discuss the change or find an existing issue.

Map ObsoleteAttribute to deprecated: true on OpenAPI operations, schemas, and schema properties.

Description

Adds built-in support for mapping ObsoleteAttribute to the OpenAPI deprecated flag on operations, schemas, and schema properties. Previously, users had to write custom IOpenApiSchemaTransformer or IOpenApiOperationTransformer implementations to achieve this.

Operations

Endpoints with [Obsolete] on the handler method (minimal APIs) or action method (MVC controllers), or added via .WithMetadata(new ObsoleteAttribute()), now automatically emit deprecated: true on the OpenAPI operation.

Schemas (types)

Types decorated with [Obsolete] produce deprecated: true on the component schema.

Schema properties

• Inline properties: [Obsolete] on a property sets deprecated: true directly on the property schema.
• Referenced properties: [Obsolete] on a property whose type is componentized sets deprecated: true on the OpenApiSchemaReference, leaving the underlying component schema unchanged. This follows the same pattern used for [Description] → x-ref-description.

Design notes

• This follows the existing conventions for [Description] → description and [Required] → required, which are all automatic with no opt-out.
• Uses inherit: false on GetCustomAttributes for type-level checks, so a derived type does not inherit deprecated from an obsolete base class.
• The behavior is on by default. Users who need to suppress it for specific cases can use an IOpenApiSchemaTransformer or IOpenApiOperationTransformer to set Deprecated = false.

Breaking change consideration

This is a behavioral change. Existing users with [Obsolete] on types, properties, or endpoints will see deprecated: true appear in their generated OpenAPI documents after upgrading. This could affect downstream codegen tools. However, we believe this is the correct default — if something is marked obsolete in .NET, it should be reflected as deprecated in the API contract.

If the team prefers an opt-in/opt-out mechanism (e.g., a property on OpenApiOptions), that can be added.

Tests

• 8 new tests covering all scenarios (type, inline property, referenced property, operations via attribute, metadata, and MVC actions)
• Full existing test suite passes (837 passed, 0 failed)

Fixes #63494

[Copilot]

Pull request overview

Adds first-class support in the OpenAPI document generator for mapping .NET [Obsolete] metadata to the OpenAPI deprecated: true flag across operations and JSON schemas, reducing the need for custom transformers.

Changes:

• Mark OpenAPI operations as deprecated when ObsoleteAttribute is present in endpoint metadata.
• Mark component schemas and inline property schemas as deprecated when the underlying type/property is [Obsolete].
• Support referenced-property deprecation via a new x-ref-deprecated annotation, plus corresponding parsing and tests.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs	Maps [Obsolete] on types/properties to schema-level deprecated or to a ref-specific annotation for componentized properties.
src/OpenApi/src/Services/OpenApiDocumentService.cs	Sets OpenApiOperation.Deprecated based on ObsoleteAttribute in endpoint metadata.
src/OpenApi/src/Services/OpenApiConstants.cs	Adds x-ref-deprecated constant for ref-only schema deprecation.
src/OpenApi/src/Schemas/OpenApiSchemaKeywords.cs	Adds the deprecated JSON schema keyword constant.
src/OpenApi/src/Schemas/OpenApiJsonSchema.Helpers.cs	Parses deprecated and x-ref-deprecated when reading schema JSON into OpenApiSchema.
src/OpenApi/src/Extensions/OpenApiDocumentExtensions.cs	Propagates x-ref-deprecated metadata onto OpenApiSchemaReference.Deprecated.
src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiSchemaService/OpenApiSchemaService.Annotations.cs	Adds tests for type/property deprecation (inline + referenced).
src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiDocumentService/OpenApiDocumentServiceTests.Operations.cs	Adds tests for operation deprecation via attribute, metadata, and MVC action attribute.

[fickleEfrit]

@dotnet-policy-service agree company="Microsoft"