--- title: OpenAPI Overlays for Environment Promotion Across Dev,... description: Most teams manage dev, staging, and production API specs as three separate OpenAPI files that inevitably drift apart. A better approach uses one canonical,... canonical: https://daily.dev/posts/openapi-overlays-for-environment-promotion-across-dev-staging-and-production-f2i10u0pn twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: OpenAPI Overlays for Environment Promotion Across Dev, Staging, and Production | daily.dev og:description: Most teams manage dev, staging, and production API specs as three separate OpenAPI files that inevitably drift apart. A better approach uses one canonical,... og:url: https://daily.dev/posts/openapi-overlays-for-environment-promotion-across-dev-staging-and-production-f2i10u0pn og:image: https://api.daily.dev/og/posts/f2I10U0pN.png og:image:alt: OpenAPI Overlays for Environment Promotion Across Dev, Staging, and Production og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # OpenAPI Overlays for Environment Promotion Across Dev, Staging, and Production **[API Evangelist](https://daily.dev/sources/apievangelist)** · 4 min read · 0 upvotes · 0 comments ## Summary 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. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### How can I avoid maintaining separate OpenAPI files for dev, staging, and production that drift out of sync? Keep one canonical, environment-agnostic OpenAPI spec and apply a thin OpenAPI Overlay per environment that only rewrites the servers block, OAuth authorization and token URLs, and the info description. The overlay's extends field points to the canonical spec's raw URL, so operations and schemas always come from the single source, eliminating drift entirely. _daily.dev surfaces practical OpenAPI patterns for teams tired of keeping specs in sync by hand._ ### What does an OpenAPI Overlay file look like for applying environment-specific server URLs and OAuth endpoints? An overlay uses the 1.1.0 overlay spec format with an extends field pointing to the canonical base spec's URL, and an actions list of JSONPath targets with update blocks. A typical environment overlay targets $.servers to swap the host, $.components.securitySchemes.OAuth2.flows.authorizationCode to repoint OAuth URLs, and $.info to inject an environment-specific warning description. _Developers wiring up multi-stage API pipelines can track OpenAPI tooling patterns like this on daily.dev._ ## Similar posts on daily.dev - [OpenAPI Overlays for Separation of Concerns When You Do Not Own the Spec](https://daily.dev/posts/openapi-overlays-for-separation-of-concerns-when-you-do-not-own-the-spec-zhy9th4pq) · API Evangelist · 0 upvotes · 0 comments - [OpenAPI Overlays for Adding Tool-Specific Content Without Polluting the Spec](https://daily.dev/posts/openapi-overlays-for-adding-tool-specific-content-without-polluting-the-spec-np7suyu3c) · API Evangelist · 0 upvotes · 0 comments - [The Many Use Cases for OpenAPI Overlays](https://daily.dev/posts/the-many-use-cases-for-openapi-overlays-1gjpvrair) · API Evangelist · 0 upvotes · 0 comments - [OpenAPI Overlays for Translating and Localizing One Canonical Spec](https://daily.dev/posts/openapi-overlays-for-translating-and-localizing-one-canonical-spec-uuthegatj) · API Evangelist · 0 upvotes · 0 comments - [Staging Environments Are a Deployment Problem, Not an Infrastructure Problem](https://daily.dev/posts/staging-environments-are-a-deployment-problem-not-an-infrastructure-problem-9pzhrxx0g) · CodeCraft Diary · 4 upvotes · 0 comments --- Tags: [#architecture](https://daily.dev/tags/architecture), [#cicd](https://daily.dev/tags/cicd), [#openapi](https://daily.dev/tags/openapi) [View this post on daily.dev](https://daily.dev/posts/openapi-overlays-for-environment-promotion-across-dev-staging-and-production-f2i10u0pn) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"OpenAPI Overlays for Environment Promotion Across Dev, Staging, and Production","url":"https://daily.dev/posts/openapi-overlays-for-environment-promotion-across-dev-staging-and-production-f2i10u0pn","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/openapi-overlays-for-environment-promotion-across-dev-staging-and-production-f2i10u0pn"},"datePublished":"2026-08-05T00:44:02.100Z","dateModified":"2026-09-14T09:31:06.061Z","description":"Most teams manage dev, staging, and production API specs as three separate OpenAPI files that inevitably drift apart. A better approach uses one canonical,...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/9cc542a459488bde149773c423cc91f7?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/9cc542a459488bde149773c423cc91f7?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"API Evangelist","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"API Evangelist","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/a36244ae67bc4f41a605f780267ecb5f","url":"https://daily.dev/sources/apievangelist"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/openapi-overlays-for-environment-promotion-across-dev-staging-and-production-f2i10u0pn","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"architecture,cicd,openapi","timeRequired":"PT4M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"API Evangelist","item":"https://daily.dev/sources/apievangelist"},{"@type":"ListItem","position":3,"name":"OpenAPI Overlays for Environment Promotion Across Dev, Staging, and Production"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/openapi-overlays-for-environment-promotion-across-dev-staging-and-production-f2i10u0pn#faq","mainEntity":[{"@type":"Question","name":"How can I avoid maintaining separate OpenAPI files for dev, staging, and production that drift out of sync?","acceptedAnswer":{"@type":"Answer","text":"Keep one canonical, environment-agnostic OpenAPI spec and apply a thin OpenAPI Overlay per environment that only rewrites the servers block, OAuth authorization and token URLs, and the info description. The overlay's extends field points to the canonical spec's raw URL, so operations and schemas always come from the single source, eliminating drift entirely. daily.dev surfaces practical OpenAPI patterns for teams tired of keeping specs in sync by hand."}},{"@type":"Question","name":"What does an OpenAPI Overlay file look like for applying environment-specific server URLs and OAuth endpoints?","acceptedAnswer":{"@type":"Answer","text":"An overlay uses the 1.1.0 overlay spec format with an extends field pointing to the canonical base spec's URL, and an actions list of JSONPath targets with update blocks. A typical environment overlay targets $.servers to swap the host, $.components.securitySchemes.OAuth2.flows.authorizationCode to repoint OAuth URLs, and $.info to inject an environment-specific warning description. Developers wiring up multi-stage API pipelines can track OpenAPI tooling patterns like this on daily.dev."}}]} ```