How-to › Ship an SDK

How to add a docs output to an existing generated SDK project#

Make docs an output of the run that generates the SDK, so their method names come from the client's own model, and prove it by running every example.

Audience
DevRel
Level
intermediate
Topic
Customize a generator without forking
Languages
TypeScript and Python
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hey API code examplesA TypeScript client from Hey API, and a reference site that reads x-codeSamplesExamples for operations with path parameters did not compile here, and its documentation offers them for TypeScript onlyYou need examples in more than one language
Kiota with a spec-built referenceKiota generates the clients and a separate team owns the reference siteThe site names operationIds while Kiota callers chain path builders, so no method name on it matches a callYour readers copy calls from the docs into code
Redocly built from the specYou want one HTML file, hosted anywhere, describing the HTTP API itselfIt documents requests and responses, never the client a reader installs, unless you feed it samplesYour docs should teach the SDK rather than the HTTP API
sdkgen docgen editionThe SDK is generated by sdkgen and its docs should change in the same commitA site styled and structured by docgen’s templates, and examples it does not compile itselfYou 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.

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

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

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.