OpenAPI 'deprecated' flag produces no actionable signal for consumers
0 reputation · 07 Jun 2025, 02:08 UTC
Our API contract is defined in OpenAPI 3.0.x, and we mark sunset operations with the standard deprecated: true property on the operation object. The flag renders correctly in Swagger UI (strikethrough styling), but that is where the signal ends: consumers only notice the deprecation if they happen to open the docs.
The goal is to turn this documented, machine-readable flag into useful alerts for client teams — for example, a CI check or generated-client warning when code still calls a deprecated operation — without flooding teams with notifications for endpoints they never touch.
The uncertainty is that the specification defines deprecated as purely informative: it carries no removal date, no replacement pointer, and triggers no runtime behavior, so any alerting has to be built on top of the spec rather than from it.
Is there an established convention (extension fields, external metadata) for attaching a removal date or successor operation to a deprecated operation in OAS 3.0.x? What granularity of scanning (spec diffing vs. runtime traffic analysis) avoids alert noise while still catching actual usage? Should alerts fire on every deprecated operation or only when a removal deadline approaches?