How-to › Ship an SDK

How to leave a SaaS SDK generator without losing your SDK#

Sort a hosted generator's SDK repository by who controls each file, move hook code into an ordinary transport, then regenerate and diff the public surface.

Audience
Platform team
Level
advanced
Topic
Choose a generator and generate an SDK
Verified

Read first: Switch SDK generators without breaking published packages

Your Go SDK regenerates only through a hosted service. Its workflow file reads your OpenAPI document from the vendor’s registry, and your request rewriting sits in a hook package that only the vendor’s output calls. A trial run of another generator renames every exported name your callers import. Cancelling the contract leaves code you own that nothing can rebuild.

What you get

You will end up with an inventory of who controls each file, a surface diff against three replacement generators, and your hook code in a transport that four clients use. This is for you if a hosted generator writes an SDK you publish.

Short answer

Sort the vendor’s SDK repository into generated output, vendor configuration, your OpenAPI document and the hook slot, and commit the document if the workflow reads it from the vendor’s registry. Move hook code into an ordinary http.RoundTripper while the vendor still generates, then regenerate with sdkgen, Kiota or ogen and diff the exported surface. Plan a major release: none of the three kept one exported name with its declaration.

You will need

Node 22 or later, Go 1.25 or later, git, the SDK repository and the document it is generated from. The page uses Go, since ogen generates Go only. Verified 2026-11-22 against @voxgig/sdkgen 4.44.3, Kiota 1.39.0 and ogen v1.24.0. The method is the surface diff of switching generators without breaking packages, applied to output you can no longer regenerate.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Fern, stayingAn Enterprise SDK whose hand-written files are listed in .fernignoreGo and custom code both need the Enterprise plan, and fern generate alone reapplies Replay patchesYou want custom Go code without an Enterprise contract
KiotaSeveral languages from one tool, with custom behavior written as HTTP middlewarePath-shaped request builders replace every method, and each language needs runtime packagesCallers want one named method per operation
ogenA Go-only SDK whose callers want methods named from operationIdsGo only, and this document failed until one construct was skipped by configurationYou ship more than Go
sdkgenEntity-shaped clients in several languages, with the module path kept through the modelEntity calls replace every method, Go takes no *http.Client, and the typed Go record came out emptyGo callers need typed records, which this release writes with no fields
Speakeasy, stayingA maintained SDK whose hook slot already holds working codeHooks need a Business or Enterprise plan, and none of the three replacements reads gen.yamlYou need to regenerate without an account

Voxgig maintains sdkgen, one of five rows sorted by name rather than by preference.

Staying with Fern or Speakeasy keeps maintained output at the cost of their formats and their plans. Kiota takes custom behavior as HTTP middleware, or in Go as a transport, but renames every call, and ogen keeps operation names in Go alone. sdkgen kept the module path through two model lines and changed everything a caller types.

Read what each vendor says you keep

Stainless takes no new SDKs, and liblab’s service has stopped. Stainless’s post, dated May 18, 2026, winds down all hosted Stainless products, the SDK generator among them, with no new signups, projects or SDKs. It tells customers “you own the SDKs you’ve generated to date”.1 liblab’s command line, 0.49.49 and tagged latest on npm, exited 2 on liblab --version and printed “The liblab service has been sunset as of July 31, 2026 and is no longer operational”, as lists/liblab-0.49.49.txt records. liblab’s migration guide moves its users to the Postman CLI, where liblab hooks add has no direct equivalent.

Speakeasy’s security and data privacy page says all generated code is owned by the customer and licensed MIT by default. Fern’s terms page says Fern is a Postman company whose terms live with Postman legal, and that customers who sign up from August 28, 2026 are under them. The Postman page loads its text by script, so this page could not read an ownership clause in it. Read it before you sign. Fern’s pricing page puts Python and TypeScript SDKs on the free plan, and Go and custom code on the Enterprise plan.

A shutdown takes what runs on the vendor’s side: the generator, its templates, and the service that reads its configuration. The repositories, packages and any copy of the document stay yours.

Sort the repository by who controls each file

generate.sh cloned two public Go SDKs that Speakeasy generated, at pinned commits, and recorded each file’s marker and the vendor’s own record of what it wrote. inventory.mjs sorts them.

node inventory.mjs
speakeasy-sdks/speakeasytryout @ 2768871, Speakeasy 1.227.0 (.speakeasy/gen.lock), release 0.9.3
  41 files outside docs/: 30 generated, 4 vendor config, 1 spec, 1 in the hook slot, 5 other
  recorded as generated but not in the repository: 1 (tests/helpers.go)
  spec: openapi.yaml, in the repository
  vendor config: .github/workflows/speakeasy_sdk_generation.yml, .speakeasy/gen.lock, files.gen, gen.yaml
  hook slot, kept across regenerations: internal/hooks/registration.go
formancehq/formance-sdk-go @ 3e294b6, Speakeasy 1.770.0 (.speakeasy/workflow.lock), release 5.0.1
  909 files outside docs/: 894 generated, 6 vendor config, 0 spec, 2 in the hook slot, 7 other
  recorded as generated but not in the repository: 0
  spec: not in the repository; .speakeasy/workflow.yaml reads registry.speakeasyapi.dev/formance/formance/stacks-source@LATEST_RELEASE
        .speakeasy/workflow.lock pins sha256:e21e54e7818b...
  vendor config: .github/workflows/sdk_generation.yaml, .github/workflows/sdk_publish.yaml, .speakeasy/gen.lock, .speakeasy/workflow.lock, .speakeasy/workflow.yaml, gen.yaml
  hook slot, kept across regenerations: internal/hooks/ledger_import.go, internal/hooks/registration.go

The formancehq/formance-sdk-go repository holds no document: its workflow reads one from Speakeasy’s registry, and the lock records only a digest. Export that document and commit it before you cancel, because a digest regenerates nothing.

The vendor config lines are the second loss. None of the three replacements reads gen.yaml or the workflow files, so every setting in them has to be found again in the next tool’s own terms.

Diff the public surface

The speakeasytryout repository keeps its document, so generate.sh regenerated it three ways. For sdkgen it generates the go target twice, the second time with two lines that keep the module path and package name.


# Keep the module path and package name the Speakeasy SDK published under.
main: kit: target: go: module: path: 'github.com/speakeasy-sdks/speakeasytryout'
main: kit: target: go: module: package: 'speakeasytryout'

tools/list-go.mjs lists every exported function, method, type, struct field and interface method a caller can import, with its declaration, and diff-surface.mjs compares each listing with the Speakeasy SDK’s.

node diff-surface.mjs
Speakeasy SDK: module github.com/speakeasy-sdks/speakeasytryout, 138 exported names
  generator module path                 same  changed  gone
  sdkgen    kept                        0     1        137
            changed: .:New
  Kiota     none written (your go.mod)  0     0        138
  ogen      none written (your go.mod)  0     2        136
            changed: .:WithClient, .:WithServerURL
list pets:
  speakeasy Pets.ListPets  func ListPets(ctx context.Context, request operations.ListPetsRequest) (*operations.ListPetsResponse, error)
  sdkgen    entity/PetEntity.ListTyped  func ListTyped(reqmatch PetListMatch, ctrl map[string]any) ([]Pet, error)
  kiota     pets/PetsRequestBuilder.Get  func Get(ctx context.Context, requestConfiguration *PetsRequestBuilderGetRequestConfiguration) ([]models.Petable, error)
  ogen      Client.ListPets  func ListPets(ctx context.Context, params ListPetsParams) (ListPetsResponse200Json, error)
the id field:
  speakeasy pkg/models/shared/Pet.ID  field int64
  sdkgen    entity/PetCreateData.Id  field int
  kiota     models/Pet.GetId  func GetId() *int32
  ogen      Pet.ID  field int
exported fields on the record type a list returns:
  speakeasy pkg/models/shared/Pet  3
  sdkgen    entity/Pet  0
  ogen      Pet  3
  kiota     models/Pet  no fields, 3 getters: GetId, GetName, GetTypeEscaped

No generator kept one name with its declaration, so the exit is a major release whichever you pick. New, WithClient and WithServerURL survived under other declarations. The id is an int64 in the Speakeasy SDK, an *int32 behind Kiota’s getter, and an int in the other two, so every caller that builds a Pet changes.

sdkgen’s typed Pet has no fields, and the allOf is not the cause. A copy of the document with Pet as a plain object gives the same empty struct, and so does 4.45.0 with apidef 8.33.1, as lists/sdkgen-pet-struct.txt records. The model’s pet entity keeps all three fields, each named under n, while the Go type writer drops any field whose name is unset. The untyped List, which returns any, is the call the demo makes.

Move the hook code out of the vendor’s slot first

In formancehq/formance-sdk-go, internal/hooks/ledger_import.go sits in Speakeasy’s hook package with no generated marker and no entry in the generator’s trackedFiles. The hooks page says the registration file there is generated once and then belongs to you. The hook keys on the operationId the generated code passes in:

func (l ledgerHook) BeforeRequest(hookCtx BeforeRequestContext, req *http.Request) (*http.Request, error) {
	switch hookCtx.HookContext.OperationID {
	case "v2ImportLogs":
		return l.handleV2ImportLogs(req)
	default:
		return req, nil
	}
}

No replacement calls internal/hooks, so the code has to move before the generator does. An http.RoundTripper works under all four clients and names the operation by method and path. The sample’s adds an idempotency key to createPets, a hook of the same kind:

func (t Transport) RoundTrip(req *http.Request) (*http.Response, error) {
	if t.Base == nil {
		closeBody(req)
		return nil, errors.New("idempotency.Transport: Base is nil")
	}
	if req.Header.Get("Idempotency-Key") != "" || !t.matches(req) {
		return t.Base.RoundTrip(req)
	}
	key, err := NewKey()
	if err != nil {
		closeBody(req)
		return nil, err
	}
	// A RoundTripper must not modify the request it was given, so the header goes on a clone.
	r := req.Clone(req.Context())
	r.Header.Set("Idempotency-Key", key)
	return t.Base.RoundTrip(r)
}

The clone is a rule the hook never had to follow: Speakeasy’s hooks.go says a BeforeRequest hook can modify the request.2

Move it while the vendor still generates: the Speakeasy SDK takes an HTTPClient through WithClient. The demo sends three calls through each client to a stand-in held to openapi.yaml.

go -C move run .
Speakeasy SDK, key from idempotency.Transport, passed with WithClient
  POST /pets           201  idempotency-key: 32 hex
  GET  /pets?limit=10  200  idempotency-key: none
  GET  /pets/7         200  idempotency-key: none
ogen client, key from idempotency.Transport, passed with WithClient
  POST /pets           201  idempotency-key: 32 hex
  GET  /pets?limit=10  200  idempotency-key: none
  GET  /pets/7         200  idempotency-key: none
Kiota client, key from idempotency.Transport, around Kiota's default handlers
  POST /pets           201  idempotency-key: 32 hex
  GET  /pets?limit=10  200  idempotency-key: none
  GET  /pets/7         200  idempotency-key: none
sdkgen client, key from idempotency.Transport, set as http.DefaultTransport
  POST /pets           201  idempotency-key: 32 hex
  GET  /pets?limit=10  200  idempotency-key: none
  GET  /pets/7         200  idempotency-key: none

sdkgen’s Go target sends through http.DefaultClient and takes a system.fetch function, not an *http.Client, so the demo swaps http.DefaultTransport for its calls, which reaches every client in the process.

Hand the same transport to Kiota and to a Go-only generator

Kiota’s Go output imports no net/http. The request adapter takes an *http.Client, and the sample wraps the transport of the one GetDefaultClient returns, so Kiota’s default handlers still run inside it. Its middleware page shows custom handlers for .NET, TypeScript and Python only. The sample pins five runtime modules below what kiota info recommends, because each recommended release declares Go 1.26, as lists/kiota-runtime.txt shows.

	hc := khttp.GetDefaultClient()
	hc.Transport = idempotency.Transport{Base: hc.Transport, Writes: writes}

ogen takes the same client through WithClient. With its default configuration it refused this document, printing the line in lists/ogen-default.txt, because the x-next response header is described with content. The configuration page says to “Use ignore_not_implemented to skip those operations instead”. In this run it skipped the header and kept the operation, so the generated ListPets never returns x-next. For per-request edits inside ogen itself, an opt-in client/editors feature exists, and code there would be tied to ogen again.

Check it worked

node --test leave.test.mjs
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1143.795188

One test fails if any generator keeps an old name with its declaration. Others refuse empty or malformed input and catch a changed signature, interface method, or field type. The rest pin the hook slot, the registry source, the empty Pet structs and the Kiota pins, then run the Go tests and the demo, which expects a key on the write alone.

When it goes wrong

The key stops arriving after the switch. The hook still sits in internal/hooks, and the replacement never calls that package. Move the code into a transport and run it under the old SDK before you regenerate.

The workflow cannot find a document to regenerate from. The vendor’s registry held it, as the lock in formancehq/formance-sdk-go shows. Export the document while the account works, and commit it beside the SDK.

The transport adds keys to the wrong calls. The hook matched an operationId and the transport matches a method and path, so a server URL with a base path such as /v1 needs Prefix. The tests check that /v1pets is not taken for /v1/pets.

When not to do this

Do not leave a vendor because a renewal is due. The diff shows a major release in every direction, and each settings file has to be rebuilt by hand.

Do not regenerate before the hook code has moved. Code in a vendor’s slot has nowhere to go in the next tool, and finding that out after the switch means debugging two changes at once.

Choose Kiota over sdkgen when your custom code is already HTTP middleware and you ship more than one language, because a Go transport and Kiota’s handlers both keep it outside generated code. Choose ogen when the SDK is Go only and callers expect one method per operation. Skip sdkgen’s Go target if callers depend on typed records, since this release writes them with no fields.

Last verified

Verified 2026-11-22 against Node 22.23.5, Go 1.25.0, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3 with @voxgig/apidef 8.32.4, Kiota 1.39.0 and ogen v1.24.0. Every output block is what the command preceding it printed. The generators, the clones and liblab’s command line ran in generate.sh, with no account, and their output is committed. Speakeasy and Fern need an account, so neither was run. Their terms, plans and hooks come from the pages linked here, read on 2026-11-22 with Stainless’s post and liblab’s guide.

Footnotes

  1. The post’s page shows the date May 18, 2026, and its article:published_time metadata says May 15. This page gives the date the post shows its readers, who are sent to a transition page for help moving to other options. ↩︎ Back to text

  2. The rule is in the comment on the interface itself. net/http says RoundTrip should not modify the request, except for consuming and closing the Request’s Body, and that it must always close the body, including on errors. The Speakeasy SDK hands the request a hook returned to its HTTPClient, so the same value passes from a seam that may edit it to one that may not. ↩︎ 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.