How-to › Ship an SDK

How to switch SDK generators without breaking published packages#

Move an SDK from OpenAPI Generator to another generator under the same package names, diff the public surface, and keep or retire each old name on purpose.

Audience
Platform team
Level
advanced
Topic
Choose a generator and generate an SDK
Languages
TypeScript, Python and Go
Verified

Your Bookshelf SDK is on npm as @acme/bookshelf, on PyPI as bookshelf, and at github.com/acme/bookshelf-go/v2, all from OpenAPI Generator. The replacement generator’s first run publishes as @voxgig-sdk/bookshelf-sdk, imports as bookshelf_sdk, and exports no DefaultApi. Every caller who upgrades gets an import error, although the version number promised a compatible release.

What you get

You will end up with the replacement SDK under your published names, a per-language diff of the public surface, and a compatibility layer for the calls users make. This is for you if your users install an SDK you generate.

Short answer

Generate the replacement on a branch under the registry names you already publish: sdkgen sets them per target in the project model, openapi-python-client takes name overrides, and orval writes into your own package.json. Then list the old and new exports and compare. Shim the names callers use, ship the rest as a major, and check the import path too, because sdkgen keeps a Python import name of its own.

You will need

Node 22 or later, Python 3.12 or later, an SDK already published from OpenAPI Generator output, and the OpenAPI document it came from. The sample’s api.json is the five-operation Bookshelf document. generate.sh builds the published SDK with OpenAPI Generator, then the candidates, and commits a surface listing for each, so the commands below run offline.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
A compatibility shimCallers use a few operations, and you can carry two naming schemes for one majorTwo names per operation until it is deleted, and old options it must refuseCallers import the old runtime’s helpers
openapi-python-clientA Python SDK whose distribution and import name must both stayOne module of functions per operation, so DefaultApi and ApiClient are goneYou also publish TypeScript or Go from the document
orvalA TypeScript SDK whose package.json you keep and ownFunctions in one file, so DefaultApi, Configuration and the model helpers are goneCallers construct API classes
sdkgenTypeScript, Python and Go from one model, with each registry name set thereA Python import name fixed at <name>_sdk, and entity calls in place of DefaultApiPython callers must keep their import line with no shim

Voxgig maintains sdkgen, which this page runs alongside two other generators and does not recommend over them.

openapi-python-client keeps both Python names through configuration, where sdkgen needs a shim package for the import name. orval keeps the npm name because it writes no package.json, and that same choice leaves the versioning to you. All three change nearly every exported name.

Keep the published names in the model

sdkgen derives a name per registry from the project: @voxgig-sdk/bookshelf-sdk, voxgig-sdk-bookshelf-sdk, and github.com/voxgig-sdk/bookshelf-sdk/go. The model reference lists publish.registry.package, module.path and module.package per target, and generate.sh appends these lines to .sdk/model/project.aontu before it generates again.


# Publish under the names the OpenAPI Generator packages used. A Go module at v3 or above
# needs the major version at the end of its path, so the Go import path moves from /v2 to /v3.
main: kit: target: ts: publish: registry: package: '@acme/bookshelf'
main: kit: target: py: publish: registry: package: 'bookshelf'
main: kit: target: go: module: path: 'github.com/acme/bookshelf-go/v3'
main: kit: target: go: module: package: 'bookshelf'
main: kit: target: &: publish: version: '3.0.0'

The Go line is not optional. The Go modules reference requires a module at major version 2 or higher to end its path with that suffix, so a Go major is an import-path change by rule.

Diff the public surface

tools/list-surface.mjs reads a TypeScript entry through the TypeScript compiler API and a Go module’s root package from source. tools/list_surface.py reads a Python package’s __init__.py with ast. diff-surface.mjs compares each listing with the published one. API Extractor is built to flag a pull request that changes a TypeScript package’s API contract, which suits a team that wants this check in CI.

node diff-surface.mjs
TypeScript: @acme/bookshelf 2.3.0 from OpenAPI Generator
  sdkgen, derived names              package @voxgig-sdk/bookshelf-sdk (changed)
                                     old exports kept: 1 of 53
  sdkgen, names kept                 package @acme/bookshelf
                                     old exports kept: 1 of 53
  sdkgen, names kept, compat/        package @acme/bookshelf
                                     old exports kept: 12 of 53, 13 methods gone, 5 signatures changed
  orval, same package.json           package @acme/bookshelf
                                     old exports kept: 1 of 53
Python: bookshelf 2.3.0, import bookshelf, from OpenAPI Generator
  sdkgen, derived names              distribution voxgig-sdk-bookshelf-sdk (changed), import bookshelf_sdk (changed)
                                     old exports kept: 0 of 11
  sdkgen, names kept                 distribution bookshelf, import bookshelf_sdk (changed)
                                     old exports kept: 0 of 11
  sdkgen, names kept, py-compat/     distribution bookshelf, import bookshelf
                                     old exports kept: 0 of 11
  openapi-python-client, overrides   distribution bookshelf, import bookshelf
                                     old exports kept: 0 of 11
Go: github.com/acme/bookshelf-go/v2, package bookshelf, from OpenAPI Generator
  sdkgen, derived names              module github.com/voxgig-sdk/bookshelf-sdk/go (changed), package voxgigbookshelfsdk (changed)
                                     old exports kept: 0 of 51
  sdkgen, names kept, /v3 path       module github.com/acme/bookshelf-go/v3 (changed), package bookshelf
                                     old exports kept: 0 of 51
still removed with compat/: 41 TypeScript names, among them ApiResponse, BaseAPI, BlobApiResponse, BookFromJSON
  methods gone: DefaultApi.createBookRaw, DefaultApi.createBookRequestOpts, DefaultApi.deleteBookRaw and 10 more
  signatures changed: DefaultApi.createBook, DefaultApi.deleteBook, DefaultApi.getBook, DefaultApi.listBooks, DefaultApi.updateBook

The model lines fixed every registry name. The Python import did not move: 16 components of the py target write the package as <Name>_sdk, so pip install bookshelf installs a package that import bookshelf cannot find.1 record-py-import.sh tried module.name, which the model reference lists, in project.aontu, where it fails to unify with the target’s own value, and in the target’s model file, where the package stays bookshelf_sdk. sdkgen 4.45.0 did the same, as py-import-name.txt records.

The one TypeScript export all three candidates share is the Book model type. The diff also reads each kept class’s methods: compat/ keeps the five operations but drops 13 helpers such as listBooksRaw, and each operation lost the initOverrides parameter.

Decide each difference: shim or major

Removing an exported name is a breaking change under semantic versioning, so the choice is per name. compat/ keeps the five operations, Configuration, and the three error classes on top of the sdkgen SDK, and marks DefaultApi deprecated. An initOverrides argument it cannot honor is refused rather than dropped. Its fetch hands the SDK a copy of each response, so the response on a ResponseError is the one the API sent, still unread.

export class DefaultApi {
  #sdk
  constructor(configuration = new Configuration()) {
    const fetch = observed(configuration.fetchApi)
    this.#sdk = new BookshelfSDK({ base: configuration.basePath, system: { fetch } })
  }

  async listBooks(...rest) {
    noOverrides(rest, 'listBooks')
    return call(async () => (await this.#sdk.Book().list()).map((b) => b.data()))
  }

run-old-caller.mjs runs code written against the published package, unchanged, against that package and against the shim, each with a fresh stand-in for the API.

node run-old-caller.mjs
OpenAPI Generator 2.3.0
  listBooks   Emma
  createBook  b2 Persuasion
  updateBook  Persuasion, 2nd ed. (1817)
  deleteBook  done
  getBook     ResponseError, status 404
              application/json {"error":"no book b2"}
  requests    GET /books, POST /books, PATCH /books/b2, DELETE /books/b2, GET /books/b2
sdkgen 3.0.0 with compat
  listBooks   Emma
  createBook  b2 Persuasion
  updateBook  Persuasion, 2nd ed. (1817)
  deleteBook  done
  getBook     ResponseError, status 404
              application/json {"error":"no book b2"}
  requests    GET /books, POST /books, PATCH /books/b2, DELETE /books/b2, GET /books/b2

The 41 names the shim leaves out come from the generated runtime and model files, BaseAPI, Middleware, and the BookFromJSON helpers among them. They decide the version, with the 13 methods and the five signatures. Keep them all and the release can be a minor, or drop them and ship 3.0.0 with the shim as the migration path, as here.

Keep the Python import name with a shim package

py-compat/bookshelf/__init__.py re-exports the sdkgen client under the old import name and warns once on import. It keeps the import line and nothing else of the old package.

python3 check_py_compat.py
import bookshelf        -> bookshelf_sdk.BookshelfSDK
same class as bookshelf_sdk.BookshelfSDK: True
DeprecationWarning: import bookshelf_sdk instead of bookshelf; bookshelf is removed in 4.0.0
from bookshelf import DefaultApi           -> ImportError
import bookshelf.api.default_api           -> ModuleNotFoundError
from bookshelf.entity import book_entity   -> ModuleNotFoundError
isinstance across the two names: True
pickled as: bookshelf_sdk.BookshelfSDK

Code written against OpenAPI Generator’s DefaultApi still fails, and so does a submodule import under the old name. The shim serves callers who moved to BookshelfSDK and kept import bookshelf. The generated pyproject.toml packages bookshelf_sdk* only, so the shim needs adding to its include line before it ships.

Keep the names with openapi-python-client and orval

openapi-python-client takes project_name_override and package_name_override from a configuration file, as its README documents, and both held. orval writes the client into a path you choose and no package.json, which generate.sh checks, so the name stays wherever your manifest says.

echo "[4/5] openapi-python-client 0.30.0, with the project and package names kept"
mkdir -p opc && printf 'project_name_override: bookshelf\npackage_name_override: bookshelf\n' > opc/config.yml
(cd opc && uvx --from openapi-python-client==0.30.0 openapi-python-client generate --path ../api.json --config config.yml --output-path out >/dev/null 2>&1)
list_py opc/out/pyproject.toml opc/out/bookshelf > "$S/opc-py.json"
(cd opc/out && find bookshelf -name '*.py' | LC_ALL=C sort) > "$S/opc-py-files.txt"

echo "[5/5] orval 8.48.0, fetch client, in the package.json the published SDK already has"
mkdir -p orval/src && cp oag/ts/package.json orval/package.json
(cd orval && npx --yes orval@8.48.0 --input ../api.json --output ./src/bookshelf.ts --client fetch >/dev/null 2>&1)

Neither keeps the old surface. openapi-python-client exports Client, AuthenticatedClient, and a module per operation, as generated/surface/opc-py-files.txt lists, in place of OpenAPI Generator’s eleven names. orval exports 26 names, listBooks among them, as a function that resolves to { data, status, headers } rather than to the books, as generated/orval/bookshelf.ts shows. A shim over either is the same work as compat/.

Check it worked

node --test migrate.test.mjs
1..17
# tests 17
# suites 0
# pass 17
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1825.932696

The first test asserts the two preceding transcripts are equal, request for request. Others pin the identities in the diff, the shim’s warning and its limits, and the include line. Four test the errors the shim throws for a JSON body, a text body, an empty body, concurrent calls, and a request with no response. Two feed compare a listing with no exports, a removed method, and a changed signature, and one deletes a listing and expects the diff run to fail.

When it goes wrong

Callers upgrade and their middleware stops running. A shim that accepts new Configuration({ middleware }) and ignores the option does that. compat/ refuses each Configuration option and initOverrides argument it cannot honor with a TypeError, which tests check, so the caller learns before any request goes out.

Callers catch ResponseError, and await err.response.json() throws. The sdkgen error keeps the status, the headers and a JSON body, and has read the body already, so a shim that builds a new Response from it loses a text body. Keep the response the transport returned, as compat/ does.

pip install succeeds and import bookshelf fails. The distribution kept its name and the import did not. Ship py-compat/ inside the same distribution, or say in the release notes that the import line changes.

Go users run go get -u and stay on 2.3.0. The -u flag upgrades each module to its latest version, and the /v3 path is a different module. Announce the new import path in the release notes.

When not to do this

Do not switch generators to fix a naming problem. A rename inside OpenAPI Generator, with a mapping or an overlay and a deprecated alias, can ship as a minor. A switch costs a major in Go by rule and in TypeScript by the diff.

Do not ship the switch as a minor on the strength of a passing old caller. The caller covers the names it uses, and the surface diff lists 41 it does not.

Pick openapi-python-client when the SDK you publish is Python only and the import line must not change, which it does through configuration and sdkgen does not. Pick orval when your TypeScript users already call functions and you want to keep owning the package manifest.

Last verified

Verified 2026-11-21 against Node 22.23.5, Python 3.13.18, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, OpenAPI Generator 7.27.0, openapi-python-client 0.30.0, orval 8.48.0, and TypeScript 5.9.3. Every output block is what the command preceding it printed. All four generators ran once, in generate.sh, and the listings and the code the commands read are committed under generated/. sdkgen 4.45.0 ran once, in record-py-import.sh, and wrote the same Python package name.

Footnotes

  1. The Python Packaging User Guide keeps a page on the difference between a distribution package, the name pip installs, and an import package, the name an import statement finds. Its example is Pillow, which installs as Pillow and imports as PIL, for historical reasons. The same page warns against installing a PyPI package foo on seeing import foo, which may install an unintended, even malicious, package. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.