--- title: OpenAPI Overlays for SDK Generation Prep: Fixing a Spec... description: When running code generators against OpenAPI specs, the output often reflects poor spec design choices made for human readers rather than generators. The... canonical: https://daily.dev/posts/openapi-overlays-for-sdk-generation-prep-fixing-a-spec-before-codegen-djq72gnix twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: OpenAPI Overlays for SDK Generation Prep: Fixing a Spec Before Codegen | daily.dev og:description: When running code generators against OpenAPI specs, the output often reflects poor spec design choices made for human readers rather than generators. The... og:url: https://daily.dev/posts/openapi-overlays-for-sdk-generation-prep-fixing-a-spec-before-codegen-djq72gnix og:image: https://api.daily.dev/og/posts/DJq72GNIX.png og:image:alt: OpenAPI Overlays for SDK Generation Prep: Fixing a Spec Before Codegen 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 SDK Generation Prep: Fixing a Spec Before Codegen **[API Evangelist](https://daily.dev/sources/apievangelist)** · 4 min read · 0 upvotes · 0 comments ## Summary When running code generators against OpenAPI specs, the output often reflects poor spec design choices made for human readers rather than generators. The recommended fix is to use OpenAPI Overlays to apply codegen-specific transformations (renaming operationIds, adding tags for namespacing, converting loose strings to enums, adding vendor extensions) inside the SDK build pipeline only — keeping the canonical spec clean and tool-neutral. Two concrete overlay examples are shown: one for naming and namespace grouping, another for type tightening and Speakeasy-specific extensions like cursor pagination. This avoids quietly forking the API's source of truth into build-pipeline convenience hacks. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Similar posts on daily.dev - [OpenAPI Overlays for Improving Developer Experience: Enriching a Thin, Code-Generated Spec](https://daily.dev/posts/openapi-overlays-for-improving-developer-experience-enriching-a-thin-code-generated-spec-qiejsxc37) · 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 - [OpenAPI Overlays for Test Fixtures and Mock Generation](https://daily.dev/posts/openapi-overlays-for-test-fixtures-and-mock-generation-exq9pkj6h) · API Evangelist · 0 upvotes · 0 comments - [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 - [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 --- Tags: [#architecture](https://daily.dev/tags/architecture), [#openapi](https://daily.dev/tags/openapi) [View this post on daily.dev](https://daily.dev/posts/openapi-overlays-for-sdk-generation-prep-fixing-a-spec-before-codegen-djq72gnix) ```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 SDK Generation Prep: Fixing a Spec Before Codegen","url":"https://daily.dev/posts/openapi-overlays-for-sdk-generation-prep-fixing-a-spec-before-codegen-djq72gnix","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/openapi-overlays-for-sdk-generation-prep-fixing-a-spec-before-codegen-djq72gnix"},"datePublished":"2026-07-15T12:35:37.389Z","dateModified":"2026-07-15T12:47:44.827Z","description":"When running code generators against OpenAPI specs, the output often reflects poor spec design choices made for human readers rather than generators. The...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/88c5ef43b1ec33daba1ccf0d7636acef?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/88c5ef43b1ec33daba1ccf0d7636acef?_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-sdk-generation-prep-fixing-a-spec-before-codegen-djq72gnix","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"architecture,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 SDK Generation Prep: Fixing a Spec Before Codegen"}]} ```