# 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.

Source: https://voxgig.com/howto/keep-sdk-code-samples-in-sync

- Audience: library-maintainer
- Level: advanced
- Languages: typescript, python, go, php, ruby, lua
- Verified: 2026-11-20
- Published: 2026-11-20

## 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

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Hand-written per-language samples](https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-code-samples) | One or two languages, and a reviewer fluent in each | Every API change is six edits by hand, and nothing fails when one is missed | You ship more languages than you have reviewers |
| [Hey API code examples](https://heyapi.dev/docs/openapi/typescript/plugins/sdk) | A TypeScript client from Hey API, with examples written into its copy of the spec | Examples for TypeScript only, and its example for an operation with required inputs passed none | You ship more than one language |
| [HTTPSnippet](https://github.com/Kong/httpsnippet) | You document the raw HTTP API and want curl, Python and Go versions of one request | Shows a bare HTTP call rather than the SDK, and version 3.0.10 has no Lua target | Your readers install an SDK and copy its calls |
| [sdkgen docgen examples](https://github.com/voxgig/docgen) | Your SDKs come from sdkgen, and samples should change when the model changes | Examples it states are not compiled or run, so CI has to run them | Your SDKs come from another generator |
| [Speakeasy code samples overlay](https://www.speakeasy.com/docs/sdks/sdk-docs/code-samples/generate-code-samples) | Speakeasy generates the SDKs and the reference reads `x-codeSamples` | An account and Speakeasy's workflow for each target language | You want the samples without a hosted generator |
| [Swagger Codegen API docs](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/) | You already run Swagger Codegen, and per-client Markdown docs are enough | Examples in some languages only, with a placeholder key a caller may copy | You 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.

```bash title="generate.sh"
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.

```bash
node samples.mjs
```

```text output
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](https://spec.openapis.org/overlay/v1.0.0.html) 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`.

```bash
node overlay.mjs
```

```text output
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.

```bash
node check.mjs
```

```text output
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.

```bash
node header.mjs
```

```text output
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.

```bash
node swagger.mjs
```

```text output
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](https://github.com/swagger-api/swagger-codegen), which reads Swagger 2.0 documents.

Hey API's examples come from its TypeScript SDK plugin. Its Python generator,
[`@hey-api/openapi-python`](https://heyapi.dev/docs/openapi/python/get-started), 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`.

```bash
node heyapi.mjs
```

```text output
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.

```bash
node --test samples.test.mjs
```

```text output
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](https://peps.python.org/pep-0008/) 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.

## Related how-tos

- [Detect a reference site drifting from its OpenAPI spec](/howto/check-a-reference-site-in-ci)

- [Choose a renderer for your OpenAPI reference site](/howto/choose-a-reference-docs-renderer)

- [Turn a breaking release changelog into a migration guide](/howto/changelog-to-a-migration-guide)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Add a docs output to an existing generated SDK project](/howto/add-a-docs-output-to-a-generated-sdk)

## 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.

[^1]: `x-codeSamples` began as `x-code-samples`, and
[Redocly's page on the extension](https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-code-samples)
still mentions the earlier spelling. [Speakeasy's code samples guide](https://www.speakeasy.com/docs/sdks/sdk-docs/code-samples/generate-code-samples)
calls the extension widely accepted, which is as close as a vendor extension gets to a standard.

[^2]: The [Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) 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.