Your reference site tells TypeScript users to call getBook, while the SDK you shipped exposes
client.Book().load(). The site is built from the OpenAPI document and the client from a
generator’s model, in two pipelines that never compare notes. Each rename in the SDK leaves a page
that sends readers to a method that does not exist.
What you get
You will end up with a docs site written by the same run that writes the SDK, and a test that runs every example on it against the generated clients. This is for you if you publish SDKs and the docs keep naming methods the SDKs do not have.
Short answer
In an sdkgen project, switch on docgen’s github-pages edition in .sdk/model/project.aontu and
regenerate. The run writes a static site to docs/ from the same model as the SDK, with an example
per target on each entity page. Put hand-written guides in .sdk/doc/content, never in docs/.
Then run the examples against the generated clients. Kiota writes no docs, and Hey API writes
examples into a copy of the spec.
You will need
Node 22 or later, Python 3, and a generated SDK project you can regenerate. The sample scaffolds
the Bookshelf API for the ts and py targets.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hey API code examples | A TypeScript client from Hey API, and a reference site that reads x-codeSamples | Examples for operations with path parameters did not compile here, and its documentation offers them for TypeScript only | You need examples in more than one language |
| Kiota with a spec-built reference | Kiota generates the clients and a separate team owns the reference site | The site names operationIds while Kiota callers chain path builders, so no method name on it matches a call | Your readers copy calls from the docs into code |
| Redocly built from the spec | You want one HTML file, hosted anywhere, describing the HTTP API itself | It documents requests and responses, never the client a reader installs, unless you feed it samples | Your docs should teach the SDK rather than the HTTP API |
| sdkgen docgen edition | The SDK is generated by sdkgen and its docs should change in the same commit | A site styled and structured by docgen’s templates, and examples it does not compile itself | You need a docs platform with versioning, analytics, or a hosted search |
Voxgig maintains sdkgen. It is one of four options here, not the recommendation.
A spec-built site such as Redocly’s is the easier one to host, theme and search, and it describes the API correctly. It describes the client only when someone supplies samples. docgen describes the client because it reads the model the client came from, at the cost of a site whose shape its templates decide. Hey API sits between them, writing client examples into a copy of the document.
Switch on the website edition
A project scaffolded by @voxgig/create-sdkgen already holds two docgen editions: summary, which
is on and writes SUMMARY.md, and github-pages, which is off. Turn the website on in the project
overlay, which sdkgen never overwrites, add a guide where docgen reads authored pages, and
regenerate.
printf "\nmain: kit: doc: edition: 'github-pages': active: true\n" >> model/project.aontu
mkdir -p doc/content
cp "$HERE/hand/deploy.md" doc/content/deploy.md
npm run generate
sdkgen 4.44.3 has no docs add action and stops with Unknown action: docs. A project without
the edition, with @voxgig/docgen installed, adds it with npx voxgig-sdkgen edition add github-pages, and it arrives switched off, so the overlay line is still needed. The
docgen README lists the edition’s other settings: output
path, colors, a target filter, and the authored-pages folder.
The run wrote 16 files under docs/: an API page per entity, a page per SDK target and per
feature, four guides, search, styles, and the hand-written guide as docs/additional/deploy.html.
docgen records each file it generated in .sdk/doc/generated.json, and its README says a later run
removes a recorded page once the model stops producing it.1
Run the examples the site shows
Each entity page carries one example per target. The docgen README says they come from the model
and are not compiled or executed, so a test has to run them. examples.mjs pulls both code blocks out of
site/api/book.html and runs each line against the SDK from the same run, in the SDK’s test mode,
with no network.
node examples.mjs
site/api/book.html: 2 examples, py and ts
py against generated/py, test mode
Book().list ok
Book().load ok
Book().create ok
Book().update ok
Book().remove ok
ts against generated/ts, test mode
Book().list ok
Book().load ok
Book().create ok
Book().update ok
Book().remove ok
Ten calls ran. The names in the docs and the methods on the client came from one model, and running the examples checks that rather than assuming it.
Keep guides out of the generated folder
docgen overwrites any page it generates, and leaves a file it never recorded where it is. That
second rule makes docs/ look safe for guides until the model grows. The sample saved two
hand-written pages inside docs/, edited a generated one, regenerated, then added a Go target and
regenerated again.
cat runs/pitfall.txt
after regenerate
docs/guides/deploy.html kept: yes
docs/sdks/go.html kept: yes
docs/guides/first-call.html edit kept: no
after target add go and regenerate
docs/guides/deploy.html kept: yes
docs/sdks/go.html kept: no
docs/additional/deploy.html present: yes
The edit to a generated page went on the first run. The Go guide survived until the project gained
a Go target, when docgen wrote its own docs/sdks/go.html over it without a warning. Keep every
authored page in .sdk/doc/content, which docgen copies to docs/additional/ on each run.
Get docs from the same run in Kiota and Hey API
Kiota writes no documentation. None of the options kiota generate lists on its
usage page produces any, and its run here
wrote four TypeScript files and kiota-lock.json. The client it wrote names no call after an
operationId, so a reference built from the spec names getBook while a caller writes
client.books.byBookId(id).get(). Build the reference from the spec in the same CI job that runs kiota generate, and add your own
Kiota-shaped x-codeSamples with an overlay if readers copy calls from it.
Hey API’s TypeScript SDK plugin takes examples, which writes a code example for each operation
into its copy of the document, and output.source
saves that copy as source.json. Redocly’s build-docs rendered it, and its
x-codeSamples page
says such samples appear in the right panel. heyapi.mjs compiles each example against the client
Hey API wrote beside it.
node heyapi.mjs
heyapi/source.json: 5 x-codeSamples entries, lang JavaScript
GET /books await listBooks() compiles
POST /books await createBook() compiles
GET /books/{bookId} await getBook() TS2554 Expected 1 arguments, but got 0.
PATCH /books/{bookId} await updateBook() TS2554 Expected 1 arguments, but got 0.
DELETE /books/{bookId} await deleteBook() TS2554 Expected 1 arguments, but got 0.
The three operations with a path parameter got examples with no arguments, and every sample is labeled JavaScript. Every name matches the client, which is what the option buys, so compile the examples in CI before you publish them.
Check it worked
docs.test.mjs runs the site’s examples in both languages, compiles Hey API’s, and reads the
pitfall and edition results, in eleven tests.
node --test docs.test.mjs
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0
The one that matters most renames list to listBooks in both examples and expects each run to
fail. Without that test, an example harness that never reaches the SDK would pass as well.
When it goes wrong
npm run generate writes no docs/ folder. The edition is still active: false. Set it in
.sdk/model/project.aontu, the file the docgen README names for project settings, and run
npm run generate again.
A guide disappears after a regenerate. It sat at a path docgen now generates, as docs/sdks/go.html
did. Move it to .sdk/doc/content and link to docs/additional/ instead.
The TypeScript examples fail with Cannot find module './entity/BookEntity'. The compiled SDK is
CommonJS, and a package.json in a parent folder with "type": "module" makes Node load it as
ESM. Put a package.json with "type": "commonjs" nearer to it, as this sample’s own does.
When not to do this
Do not switch on the website edition to replace a docs platform you already run. docgen writes a static site in its own structure, and tutorials, versioned guides, and search analytics still need somewhere else to live. Feed that platform the examples instead.
Do not use sdkgen’s docgen for an API whose docs must describe the HTTP calls rather than a client. A Redocly site built from the spec is easier to host, theme and search, and the better choice when the readers use curl rather than an SDK.
Prefer Kiota when your clients must follow the URL structure exactly, since its builders mirror
the paths a spec-built reference already shows. Hey API is the better choice for
a TypeScript-only client whose reference site already renders x-codeSamples, once the examples
compile.
Do not publish an example nobody ran. docgen states that its examples are not executed, and Hey API’s failed to compile for three of five operations here.
Related how-tos
Last verified
Verified 2026-11-20 against Node 22.23.5, Python 3.13.18, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/docgen 0.30.9, @hey-api/openapi-ts 0.99.0, @redocly/cli
2.82.0, TypeScript 5.9.3 and Kiota 1.38.0. sdkgen, Hey API, Redocly and Kiota each ran once, in
generate.sh, and their output is committed. The commands shown run the committed SDKs and
compile Hey API’s examples. Redocly ran with REDOCLY_TELEMETRY=off.
Footnotes
-
The record in this run is version 2 of itself. The docgen README treats it as untrusted data, so an absolute path, a path containing
..or a path through a symlink prunes nothing and is reported instead. A documentation generator that declines to delete what its own notes tell it to delete is taking its notes seriously. ↩︎ Back to text