[release/11.0-preview7]: Map [Obsolete] to deprecated in OpenAPI

[Copilot]

Manual backport of #66355 to release/11.0-preview7.

Maps [Obsolete] attributes to deprecated: true in generated OpenAPI documents for operations, component schemas, and schema properties.

Description

• Operations: Endpoints with [Obsolete] on handler method or via .WithMetadata(new ObsoleteAttribute()) emit deprecated: true
• Type schemas: Types decorated with [Obsolete] produce deprecated: true on the component schema
• Inline properties: [Obsolete] on a primitive/non-componentized property sets deprecated: true directly on the property schema
• Reference properties: [Obsolete] on a componentized property sets deprecated: true on the OpenApiSchemaReference via x-ref-deprecated annotation (underlying component schema unchanged)
• OpenAPI 3.0 limitation: sibling properties alongside $ref are not allowed by the spec, so reference properties do not carry deprecated in 3.0 output

New constants: DeprecatedKeyword, RefDeprecatedAnnotation. No opt-out mechanism; users can suppress via transformer if needed.

Customer Impact

Users with [Obsolete]-annotated types, properties, or endpoints will now see deprecated: true in generated OpenAPI output automatically, without needing custom transformers. Behavioral change: existing documents will gain new deprecated fields after upgrading.

Regression?

• Yes
• No

Risk

• High
• Medium
• Low

Behavioral change to OpenAPI document output — any downstream codegen tools consuming the document may be affected by newly-appearing deprecated fields.

Verification

• Manual (required)
• Automated

1019 unit tests pass; 8 new tests covering all scenarios (operation attribute, operation metadata, MVC action, type schema, inline property, reference property, negative cases).

Packaging changes reviewed?

• Yes
• No
• N/A

---

When servicing release/2.3

• Make necessary changes in eng/PatchConfig.props

[Copilot]

Pull request overview

Backports OpenAPI deprecation support to release/11.0-preview7 by mapping [Obsolete] metadata onto deprecated: true across generated OpenAPI operations and schemas, including proper handling of $ref-based schemas via reference annotations.

Changes:

• Set OpenApiOperation.Deprecated when an endpoint has ObsoleteAttribute metadata.
• Emit deprecated: true for component schemas and inline property schemas when the corresponding type/property is [Obsolete], and flow deprecated state onto schema references via a new x-ref-deprecated metadata annotation.
• Add/extend unit + integration snapshot coverage, and introduce a sample “obsolete” document + endpoints used by snapshot tests.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/OpenApi/src/Services/OpenApiDocumentService.cs	Marks operations as deprecated when ObsoleteAttribute is present in endpoint metadata.
src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs	Maps [Obsolete] on types/properties to schema deprecated state (inline + componentized/reference scenarios).
src/OpenApi/src/Services/OpenApiConstants.cs	Adds RefDeprecatedAnnotation constant (x-ref-deprecated).
src/OpenApi/src/Schemas/OpenApiSchemaKeywords.cs	Adds DeprecatedKeyword constant (deprecated).
src/OpenApi/src/Schemas/OpenApiJsonSchema.Helpers.cs	Enables JSON parsing of deprecated and x-ref-deprecated into schema model fields/metadata.
src/OpenApi/src/Extensions/OpenApiDocumentExtensions.cs	Promotes x-ref-deprecated metadata onto OpenApiSchemaReference.Deprecated.
src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiDocumentService/OpenApiDocumentServiceTests.Operations.cs	Adds tests validating operation deprecated mapping from attribute/metadata and MVC actions.
src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiSchemaService/OpenApiSchemaService.Annotations.cs	Adds tests for deprecated mapping on obsolete types and both inline/reference properties.
src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs	Adds “obsolete” document to the integration test matrix.
src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt	Updates localization snapshot to include new obsolete endpoints/schemas output.
src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_0/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=obsolete.verified.txt	Adds OpenAPI 3.0 snapshot for “obsolete” document (no sibling deprecated on $ref property).
src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_1/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=obsolete.verified.txt	Adds OpenAPI 3.1 snapshot for “obsolete” document.
src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_2/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=obsolete.verified.txt	Adds OpenAPI 3.2 snapshot for “obsolete” document.
src/OpenApi/sample/Program.cs	Registers the new “obsolete” OpenAPI document and maps corresponding endpoints in the sample app.
src/OpenApi/sample/Endpoints/MapObsoleteEndpoints.cs	Adds sample endpoints and DTOs annotated with [Obsolete] to drive integration snapshots.