Most teams manage dev, staging, and production API specs as three separate OpenAPI files that inevitably drift apart. A better approach uses one canonical, environment-agnostic OpenAPI spec combined with thin per-environment Overlays that inject only environment-specific values — server URLs, OAuth endpoints, and description warnings. The Overlay's `extends` field anchors it to the canonical spec, and CI/CD pipelines apply the matching overlay at each stage. This eliminates drift entirely: new operations added once are inherited by all environments on the next build.
126 Impressions