Spec drift is the gap between your OpenAPI description and the API that actually runs. Routes get added, parameters change and old versions linger while the file stays the same. Detect it by diffing the spec against code routes and observed traffic in CI, then fail the build when they disagree.
Why drift matters for security
Spec driven testing only tests what the spec lists. The OpenAPI Specification is described as a language agnostic interface description that lets people and computers discover a service's capabilities without source code or extra documentation. If the description is wrong, the tooling that reads it is wrong too: scanners skip routes that are missing and test parameters that no longer exist.
OWASP API9 names the result a documentation blindspot and recommends generating documentation automatically from open standards as part of CI/CD.
Three kinds of drift
| Kind | Example | Security effect |
|---|---|---|
| Missing in spec | New admin route never described | Never tested by spec driven tools |
| Missing in code | Spec lists removed endpoint | Wasted test time, confusing docs |
| Mismatch | Field type, auth rule or status code differs | Tests assert the wrong behaviour |
The authentication row deserves attention. In OpenAPI, security can be declared at the top level and overridden per operation, and per the spec an empty security requirement object makes security optional for that operation. A copy and paste slip there silently documents an open endpoint, or hides a protected one.
How to detect it
- Route diff. Have the framework print its registered routes in CI and compare method and path pairs with the spec.
- Contract tests. Send example requests from the spec to a test deployment and check status codes and response shapes.
- Traffic comparison. Compare normalised paths in staging or production logs with the spec, as described in finding undocumented API endpoints.
- Review security blocks. List every operation whose security setting differs from the default and read each one.
How to fix it
- Pick a source of truth. Either generate the spec from code on every build, or generate server stubs and validation from the spec. Mixing the two invites drift.
- Fail the pull request on any diff, with a message naming the route.
- Version the spec file in the same repository as the code.
- Review spec changes like code changes, because they carry security meaning.
Try it yourself
Click through it at your own pace, or open it full screen. Think about what a scan would miss if the endpoint list it starts from were incomplete.
Quick check
Should the spec be generated from code or written first?
Either works if one side is authoritative and CI enforces it. Spec first suits new APIs with several consumers. Code first suits fast moving internal services.
Does fixing drift remove the need for a scanner?
No. A correct spec helps the scanner cover more, but the scanner still has to find the flaws.
Safeguard policies and gates can enforce checks in the pull request, and the free scan at gold.safeguard.sh/scan is a quick start for dependency risk.
Sources
Last reviewed: 19 October 2026.
