How-to › Document and support developers

How to keep code samples for six SDK languages in sync#

Generate one worked example per language from one model, publish it in the guides, and run every sample in CI so a rename or a dropped header fails the build.

Audience
Library maintainer
Level
advanced
Topic
Write guides and quickstarts
Languages
TypeScript, Python, Go, PHP, Ruby and Lua
Verified

A field rename ships in all six SDKs, and the guide still shows the old call in some of them. Each language’s sample was typed by a different person, so nobody can say which ones still run. The one in the reference panel for POST /books also leaves out the Idempotency-Key header the API requires.

What you get

You will end up with one worked example per operation in all six languages, generated from the SDK model, placed in the guides and in the OpenAPI document, and run in CI. This is for you if you maintain SDKs in several languages and their samples drift.

Short answer

With sdkgen, switch on the docgen github-pages edition: each entity page then carries the same example in every target language, derived from the model the SDKs come from. Turn those examples into an OpenAPI Overlay of x-codeSamples, and run every sample against its SDK’s test mode in CI. Swagger Codegen writes per-language docs for some targets, and Hey API writes examples for TypeScript only.

You will need

Node 22 or later, an OpenAPI 3 document, and the runtime of each language you ship. The sample’s api.json is the Bookshelf API with a required Idempotency-Key header on POST /books.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-written per-language samplesOne or two languages, and a reviewer fluent in eachEvery API change is six edits by hand, and nothing fails when one is missedYou ship more languages than you have reviewers
Hey API code examplesA TypeScript client from Hey API, with examples written into its copy of the specExamples for TypeScript only, and its example for an operation with required inputs passed noneYou ship more than one language
HTTPSnippetYou document the raw HTTP API and want curl, Python and Go versions of one requestShows a bare HTTP call rather than the SDK, and version 3.0.10 has no Lua targetYour readers install an SDK and copy its calls
sdkgen docgen examplesYour SDKs come from sdkgen, and samples should change when the model changesExamples it states are not compiled or run, so CI has to run themYour SDKs come from another generator
Speakeasy code samples overlaySpeakeasy generates the SDKs and the reference reads x-codeSamplesAn account and Speakeasy’s workflow for each target languageYou want the samples without a hosted generator
Swagger Codegen API docsYou already run Swagger Codegen, and per-client Markdown docs are enoughExamples in some languages only, with a placeholder key a caller may copyYou need one sample per language in one place

Voxgig maintains sdkgen. It is one of six options here, not the recommendation.

Samples built from the raw request, as HTTPSnippet builds them, never break when an SDK changes, because they never call one. Samples built from an SDK match the library the reader installs, but a regenerated SDK can break them, so CI has to run them. Hand-written samples read best and drift first.

Generate one example per operation in every language

docgen’s github-pages edition writes an entity page with an example per target, phrased from the sdkgen model. The scaffold installs the edition switched off, so turn it on in the project overlay.

npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json -t ts -t py -t go -t php -t rb -t lua -f idempotency
cd bookshelf-sdk/.sdk
printf "\nmain: kit: doc: edition: 'github-pages': active: true\n" >> model/project.aontu
npm run generate

samples.mjs reads site/api/book.html, the page that run wrote, and splits each language’s block into one chunk per operation.

node samples.mjs
go   list load create update remove
lua  list load create update remove
php  list load create update remove
py   list load create update remove
rb   list load create update remove
ts   list load create update remove

Thirty samples came from one model. They differ in syntax, not in shape: client:Book():load(...) in Lua, $client->Book()->load(...) in PHP, client.Book(nil).Load(..., nil) in Go.

Put the samples beside each operation

The reference shows a sample beside an operation when the document carries x-codeSamples there.1 overlay.mjs writes an OpenAPI Overlay with one action per operation, taking each operation’s method and path from the model’s points rather than from name matching, and applies it to api.json.

node overlay.mjs
codesamples.overlay.json: 5 actions, applied to api.json
  GET    /books           6 samples: Go, Lua, PHP, Python, Ruby, TypeScript
  POST   /books           6 samples: Go, Lua, PHP, Python, Ruby, TypeScript
  GET    /books/{bookId}  6 samples: Go, Lua, PHP, Python, Ruby, TypeScript
  DELETE /books/{bookId}  6 samples: Go, Lua, PHP, Python, Ruby, TypeScript
  PATCH  /books/{bookId}  6 samples: Go, Lua, PHP, Python, Ruby, TypeScript
every operation carries a sample in all six languages

The overlay is an output, regenerated with the SDKs. An action whose target matches no operation stops overlay.mjs with an error, because the Overlay specification itself allows a target that selects nothing.2

Run every sample against its own SDK

docgen’s README says its examples come from the model and are not compiled or executed. A sample that names the right method can still fail, so CI runs them. harness/run-all.mjs wraps each chunk in a program for its language, seeds the SDK’s test mode with one record, and reports each operation. It ran once against all six SDKs in generate.sh. check.mjs runs the TypeScript and Python samples again through the same harness, and reads Go, Lua, PHP, and Ruby from that run.

node check.mjs
go   5/5 ok  recorded by generate.sh
lua  5/5 ok  recorded by generate.sh
php  5/5 ok  recorded by generate.sh
py   5/5 ok  run here, generated/py in test mode
rb   5/5 ok  recorded by generate.sh
ts   5/5 ok  run here, generated/ts in test mode
every sample ran

check.mjs exits non-zero on any failure. In your own CI, run the harness for every language on each regenerate, since the gate here carries only the TypeScript and Python SDKs.

Catch the header a sample leaves out

The model records that POST /books requires Idempotency-Key, but none of the six create samples mentions it. header.mjs sends the TypeScript sample to a stand-in server that records what arrives.

node header.mjs
model: book.create requires header Idempotency-Key
docs sample: const created = await client.Book().create({ author: "example", published: 1, title: "example" })
docs samples for create that mention it: 0 of 6
client with default options
  POST /books  Idempotency-Key: absent
feature: { idempotency: { active: true } }
  POST /books  Idempotency-Key: present, 24 chars

The sample succeeds against the stand-in whether the header is there or not. Only an assertion on the request catches it. Activate the idempotency feature in the setup example the guides show, and make the CI stand-in reject a create without the header.

Get the same samples from Swagger Codegen and Hey API

Swagger Codegen writes Markdown docs with each client, and -DapiDocs=false is the switch that turns them off. It ran here for five languages.

node swagger.mjs
Swagger Codegen 3.0.85, createBook
  go                signature and parameter table, no example
  php               example, Idempotency-Key = "idempotency_key_example"
  python            example, Idempotency-Key = 'idempotency_key_example'
  ruby              example, Idempotency-Key = 'idempotency_key_example'
  typescript-fetch  no docs, 0 markdown files
  lua               not among the 41 names langs lists

The header is a required positional argument, so it cannot be dropped. The value is a fixed string, so a reader who pastes the sample sends one key for every create. An API that honors the key then treats each create after the first as a retry of it. Lua appears among the clients of the 2.x line, which reads Swagger 2.0 documents.

Hey API’s examples come from its TypeScript SDK plugin. Its Python generator, @hey-api/openapi-python, is in initial development, and its documentation lists no examples option. The TypeScript plugin’s examples option writes an x-codeSamples entry per operation into its copy of the document, and heyapi.mjs compiles the one for POST /books.

node heyapi.mjs
heyapi/source.json, POST /books, lang JavaScript: await createBook()
  as written               TS2554 Expected 1 arguments, but got 0.
  with a body, no header   TS2345 Property 'headers' is missing in type '{ body: { title: string; }; }' but required in type 'Omit<CreateBookData, "url">'.
  with the header          compiles

The generated type makes the header required, so tsc catches the omission that the sdkgen sample needed a stand-in for. The plugin’s payload option lets you supply the request each example shows.

Check it worked

samples.test.mjs asserts the coverage, the runs, and the two pitfalls in ten tests.

node --test samples.test.mjs
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0

Two rename list to listBooks, in the TypeScript and the Python sample, and expect the run to fail. Another rebuilds the overlay from the model and compares it with the committed copy, so a regenerate that changes a sample shows up as a diff.

When it goes wrong

A sample compiles and reads wrong. The Python sample calls client.Book(), a capitalized method, where PEP 8 asks for lowercase function names. One model phrases all six languages, so a reader of each language meets the house style of none of them. Have a reviewer fluent in each language read the six once per generator release.

The overlay applies and the reference shows no samples. The renderer reads another extension name, or an action’s target matched nothing. Run the coverage check on the merged document, not on the overlay.

A PHP sample fails with syntax error, unexpected token "=" in the harness. The harness passed it inside a double-quoted PHP string, which interpolated the sample’s $books. run-all.mjs passes it base64-encoded for that reason.

When not to do this

Do not generate samples for an API whose readers call it with curl. HTTPSnippet’s raw requests never break with an SDK release, and they show exactly the headers you put in the request.

Do not adopt sdkgen to get samples for SDKs another generator builds. docgen reads the sdkgen model, so its examples describe sdkgen clients only. Swagger Codegen fits better when you already generate with it and Markdown per client is enough. For a TypeScript-only SDK, Hey API has the edge, because its generated types let tsc find a missing required header.

Do not trust a generated sample because a generator wrote it. Each generator run here produced at least one sample that was wrong in a way only running it, compiling it, or checking its request showed.

Last verified

Verified 2026-11-20 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/docgen 0.30.9, Swagger Codegen 3.0.85, @hey-api/openapi-ts 0.99.0, HTTPSnippet 3.0.10 and TypeScript 5.9.3. Every generator ran once, in generate.sh, and its output is committed. The Go, Lua, PHP, and Ruby samples ran there too, once, on Go 1.24.7, Lua 5.4.6, PHP 8.3.6, and Ruby 3.3.6. The commands shown re-run the TypeScript samples and the Python ones, on Python 3.13.18. Speakeasy was not run; its code samples option comes from its documentation.

Footnotes

  1. x-codeSamples began as x-code-samples, and Redocly’s page on the extension still mentions the earlier spelling. Speakeasy’s code samples guide calls the extension widely accepted, which is as close as a vendor extension gets to a standard. ↩︎ Back to text

  2. The Overlay Specification asks only that a target’s result be zero or more objects or arrays. Zero is a permitted number of operations to add a code sample to, which is why overlay.mjs counts the samples after applying instead of trusting the actions. ↩︎ 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.