How to fix: OpenAPI document advertises deprecated operations
The served API description marks one or more operations or parameters as deprecated. They are still published as callable, so the contract advertises a route the team has already written off.
Why it matters
A deprecated route is usually the one that stopped getting attention: it keeps the old parameter handling, the old validation, and often the old authorization code, while review and test effort moves to its replacement. Publishing it in the contract tells an attacker exactly which path that is.
Marking an operation deprecated is good practice and is not itself a problem. The finding is the pairing: the document says do not use this, and the server still serves it. Treat the deprecated list as a work queue with a removal date, and pair it with a Deprecation and Sunset header on the live responses so clients find out at runtime rather than by reading the spec.
How to fix it
- 1Give every deprecated operation a removal date and track it.
- 2Emit Deprecation and Sunset headers on those routes so callers see the notice without reading the spec.
- 3Log calls to deprecated routes with the caller identity, so you know who still depends on them before removal.
- 4Delete the route and its spec entry once the sunset date passes.
Code examples
OpenAPI 3: deprecate with a stated replacement
paths:
/v1/users/search:
get:
deprecated: true
summary: 'Deprecated: use POST /v2/users/query. Removal 2027-01-01.'
responses:
'200': { description: OK }Express: announce the sunset at runtime
router.get('/v1/users/search', (req, res, next) => {
res.set('Deprecation', 'true');
res.set('Sunset', 'Fri, 01 Jan 2027 00:00:00 GMT');
res.set('Link', '</v2/users/query>; rel="successor-version"');
next();
});References
Detected automatically by VulnRadar. The check id is api-openapi-deprecated-operations-exposed, stable across every scan so you can filter or diff on it.
More api checks
- LowTRACE method referenced in API response body
- InfoREST endpoint allows DELETE
- LowGraphQL introspection field suggestions
- MediumGraphQL endpoint has no rate-limit headers
- LowOpenAPI server URL leaks internal host
- LowCORS preflight result not cached
- HighBearer token in URL query string
- MediumJSONP callback parameter accepted
Questions
- How severe is OpenAPI document advertises deprecated operations?
- VulnRadar rates this info severity in the api category. The severity is fixed per check, not scored per site, so the same finding is the same severity on every scan.
- Does VulnRadar check for this automatically?
- Yes. It runs as part of every scan under the check id api-openapi-deprecated-operations-exposed, which stays the same between runs so you can filter, diff, or gate CI on it.
- Which standards does OpenAPI document advertises deprecated operations map to?
- It maps to CWE-1059. In the OWASP Top 10 it falls under A09:2021.
Missing a check?
The detection set is open. If you know a misconfiguration this does not catch, propose it: the issue template asks for the threat model, how to detect it, the false-positive risk, and a test fixture, which is the same thing a maintainer would have to work out anyway.