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

Source: https://voxgig.com/howto/add-a-docs-output-to-a-generated-sdk

- Audience: devrel
- Level: intermediate
- Languages: typescript, python
- Verified: 2026-11-20
- Published: 2026-11-20

## 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](https://heyapi.dev/docs/openapi/typescript/plugins/sdk) | 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](https://learn.microsoft.com/en-us/openapi/kiota/using) | 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](https://redocly.com/docs/cli/commands/build-docs) | 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](https://github.com/voxgig/docgen) | 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.

```bash title="generate.sh"
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](https://github.com/voxgig/docgen) 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.

```bash
node examples.mjs
```

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

```bash
cat runs/pitfall.txt
```

```text output
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](https://learn.microsoft.com/en-us/openapi/kiota/using) 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`](https://heyapi.dev/docs/openapi/typescript/configuration/output)
saves that copy as `source.json`. Redocly's `build-docs` rendered it, and its
[x-codeSamples page](https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-code-samples)
says such samples appear in the right panel. `heyapi.mjs` compiles each example against the client
Hey API wrote beside it.

```bash
node heyapi.mjs
```

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

```bash
node --test docs.test.mjs
```

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

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

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

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

- [Generate Python docstrings and type hints from an API spec](/howto/python-docstrings-and-type-hints-from-a-spec)

- [Keep code samples for six SDK languages in sync](/howto/keep-sdk-code-samples-in-sync)

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

[^1]: The record in this run is version 2 of itself. The
[docgen README](https://github.com/voxgig/docgen) 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.