# How to build a reference site from a semantic model with docgen

> Switch on docgen's website edition in an sdkgen project, get one page per entity, and check that every operation in the spec reached a page.

Source: https://voxgig.com/howto/generate-a-reference-site-from-a-model

- Audience: api-producer
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

In an sdkgen project, set main: kit: doc: edition: 'github-pages': active: true in .sdk/model/project.aontu and run npm run generate. docgen writes static HTML under docs/, one API page per entity in the apidef model, with each route beside its SDK operation. Then check that every method and path in the spec appears on some page. Operations the model drops, such as HEAD and a token exchange, need a page you write under .sdk/doc/content.

---
## You will need

An OpenAPI 3 document, a project scaffolded by `@voxgig/create-sdkgen`, and Node 22 or later. The
sample's `api.json` is a small library API with nine operations on five paths, one of them a
[HEAD](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.3.2) check. docgen is the
documentation companion to sdkgen, and its README is, by its own account, the full
documentation.[^1]

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [docgen github-pages edition](https://github.com/voxgig/docgen) | An sdkgen project, and a reference that names the SDK call beside each route | A scaffold and a generate step, and the operations the model drops are missing until you write them | You do not generate the SDK with sdkgen |
| [hand-built mkdocs-material](https://squidfunk.github.io/mkdocs-material/getting-started/) | Reference and guides where the prose matters more than coverage | A person writes every page and keeps it in step, on a Python toolchain | The API changes faster than anyone edits pages |
| [openapi-typescript and openapi-fetch](https://openapi-ts.dev/introduction) | Typed TypeScript calls keyed by the spec's own paths | It writes types, never pages, so the site comes from another tool | You want pages from the same run as the client |
| [orval docs with TypeDoc](https://orval.dev/docs/reference/configuration/output/) | An orval client whose readers want a page per generated function | TypeDoc and its markdown plugin as dependencies, and a route on a page only for query hooks | Your client is fetch-based and readers look up routes |
| [Redoc through Redocly build-docs](https://redocly.com/docs/cli/commands/build-docs) | One HTML file that shows the spec exactly as written | The spec's own tags and order with no entity model, and paths drawn by a script | Readers need the SDK call rather than the HTTP request |

Voxgig maintains docgen, sdkgen and apidef, which this page is about. The first row says when to
leave them alone.

A spec renderer such as Redoc needs no pipeline and cannot misfile an endpoint, because it has no
model to be wrong. docgen groups pages by entity and stays in step with the SDK, and it inherits
every classification the model makes. The hand-built site wins on prose and loses on keeping up.

## Build the site from the model

[Add a docs output to an existing generated SDK project](/howto/add-a-docs-output-to-a-generated-sdk)
switches on docgen's `github-pages` edition and covers its settings. `generate.sh` makes the same
change on a fresh scaffold of `api.json`, adds `hand/direct-calls.md` as the authored page, and
commits the HTML the edition wrote under `generated/docs/`.

The installed docgen holds three editions, without a file that names an apidocs target or `mkdocs`.
`record.sh` listed them:

```bash
grep -E '^(editions|files in the docgen|WARN)' records/newest-release.txt
```

```text output
WARN or ERROR lines in the generate log of a: 0, of b: 0
editions in docgen 0.30.9: github-pages.aontu presentation.aontu summary.aontu
files in the docgen package that name apidocs: 0, mkdocs: 0
```

The site is docgen's own HTML, CSS and search script, 16 files in all, listed in
`generated/docs-files.txt`. It has an API page for each of the two entities, `book` and `health`.
Neither run logged a warning.

## Check every operation reached a page

`check-site.mjs` lists each operation in the spec and the first page whose text holds it as
`METHOD /path`, after tags, entities and code spans are stripped. It keeps underscores and
asterisks, because a path can hold them. It refuses a document with no operations, a
site with no pages, an unknown option and a `--skip` that names no directory, and exits 1 on a gap.
Skip the authored pages to see what docgen wrote by itself:

```bash
node check-site.mjs api.json generated/docs --skip additional
```

```text output
GET /books                   api/book.html
POST /books                  api/book.html
GET /books/{bookId}          api/book.html
DELETE /books/{bookId}       api/book.html
HEAD /books/{bookId}         MISSING
PATCH /books/{bookId}        api/book.html
POST /books/{bookId}/archive api/book.html (+1)
GET /health                  api/health.html
POST /oauth/token            MISSING
7 of 9 operations appear on a page, skipping additional
```

The archive action lands on the `book` page as a second route of `create`, with
`$action=archive`, because of what it answers. apidef 8.32.4 takes the resource before the verb
for an operation that names a schema, here the `Book` it answers with
([line 1687](https://github.com/voxgig/apidef/blob/v8.32.4/ts/src/guide/heuristic01.ts#L1687)).
Answer 204 with no body and the same release makes a `book_archive` entity, after
[a test](https://github.com/voxgig/apidef/blob/v8.32.4/ts/src/guide/heuristic01.ts#L2295) whose
source comment reads `No response at all means not an action`. apidef 8.33.1
[takes the resource before a verb](https://github.com/voxgig/apidef/blob/v8.33.1/ts/src/guide/heuristic01.ts#L2047)
whatever the answer. [Handle endpoints that do not map to an entity](/howto/endpoints-that-map-to-no-entity)
shows the same placement for actions on another document.

The two gaps come from apidef, not docgen. Its operation transform lists `head` among
[`IGNORED_OPS`](https://github.com/voxgig/apidef/blob/v8.32.4/ts/src/transform/operation.ts#L48),
and its heuristic switches off an entity whose only operations are token exchanges, marking it
[`auth-exchange`](https://github.com/voxgig/apidef/blob/v8.32.4/ts/src/guide/heuristic01.ts#L1658).

`record/probe.mjs` changes one input at a time and builds the model again:

```bash
grep -E '^==|archive|token\.|identical' records/probe-a.txt
```

```text output
== as written
  POST /books/{bookId}/archive -> book.create $action=archive
  model identical to "as written": true
== without the HEAD operation
  POST /books/{bookId}/archive -> book.create $action=archive
  model identical to "as written": true
== archive answers 204 with no body
  entities: book, book_archive, health
  POST /books/{bookId}/archive -> book_archive.create
  model identical to "as written": false
== token exchange with the default bearer security
  POST /books/{bookId}/archive -> book.create $action=archive
  POST /oauth/token -> token.create
  model identical to "as written": false
```

Deleting the HEAD operation leaves the model's JSON identical. The token endpoint's
`security: []` is what makes it an exchange: give it the document's bearer default and it becomes
a `token` entity.[^2] The base guide's comment on it names the other way back in, `active: true`
in `guide.aontu`, which adds a `token` class to the SDK as well as a page. `records/probe-b.txt`
gives the same answers on 8.33.1, apart from the 204 archive.

## Document the operations the model drops

An operation with no SDK method needs a page that says how to call it over HTTP. docgen copies
Markdown from `.sdk/doc/content` to `docs/additional/` and adds it to the navigation.

```md title="hand/direct-calls.md"
# Calls outside the SDK

Two operations in the Library API have no SDK method. Call them over HTTP.

## Check that a book exists

`HEAD /books/{bookId}` answers 200 when the book exists and 404 when it does not, with no body.
```

```bash
node check-site.mjs api.json generated/docs
```

```text output
GET /health                  api/health.html
POST /oauth/token            additional/direct-calls.html
9 of 9 operations appear on a page
```

## Check it worked

`check-site.test.mjs` pins both runs of the check, the edge cases of the route matcher, and the records the
rest of this page quotes.

```bash
node --test check-site.test.mjs
```

```text output
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

The same site built on sdkgen 4.45.0 and apidef 8.33.1 has the same 16 files, and `diff -r`
against the first build prints nothing, so this document has the same gaps on both releases.

## Run the same check on openapi-typescript and orval output

`record.sh` ran the checker on what each tool produces for `api.json`. It set
`REDOCLY_TELEMETRY=off`, which Redocly's [usage data page](https://redocly.com/docs/cli/usage-data)
says also turns off telemetry in the pages build-docs writes.

```bash
cat records/compare.txt
```

```text output
redoc build-docs: 0 of 9 operations appear on a page (exit 1)
redoc build-docs, by summary: 9 of 9 operations appear on a page by summary (exit 0)
orval docs, fetch client: 0 of 9 operations appear on a page (exit 1)
orval docs, fetch client, by summary: 0 of 9 operations appear on a page by summary (exit 1)
orval docs, react-query client with docs.route: 9 of 9 operations appear on a page (exit 0)
orval docs, react-query client with docs.route, by summary: 0 of 9 operations appear on a page by summary (exit 1)
redoc build-docs file: 5 of 5 paths inside a <script>, 0 of 5 in the markup outside scripts
orval docs pages: fetch 52, react-query 106
openapi-typescript paths type: 9 operations, head included: 1
```

`openapi-typescript` writes a `paths` type holding all nine operations, HEAD included, but it
writes no pages. A team on it with `openapi-fetch` builds its reference with a spec renderer.
[Redocly's build-docs](https://redocly.com/docs/cli/commands/build-docs) gave one file whose markup
holds every summary, while the paths sit only in a script the browser runs. Check that file with
`--match summary`.

orval's `output.docs` runs [TypeDoc](https://typedoc.org/). With the `fetch` client, its 52 pages
name functions but carry no route. The `route` option sits under `override.query.docs`, for query
hooks: with a client for [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview)
in React and that option, the hooks gain a `@route` line, and all nine routes reach a page.

## When it goes wrong

The check passes with `--skip` when it should fail. A misspelled directory skips nothing, so the
authored pages count as docgen's. `check-site.mjs` exits 2 on a `--skip` that names no directory
under the site, and a test holds it to that.

The check reports 7 of 9 after an apidef upgrade you expected to fix it. Both releases drop the
same two operations, so the authored page stays necessary. Keep the check in CI.

The check finds no route at all on a Redoc file. Redocly's build-docs keeps the paths in a script
that draws the page in the browser. Run the check with `--match summary`, which looks for each
operation's summary instead.

## When not to do this

Do not adopt sdkgen and docgen to get a reference site. Without a generated SDK, the entity pages
describe calls nobody makes, and Redoc gives the HTTP reference from the spec with no pipeline.

Do not trust the entity grouping without the check. It shows what apidef understood, which for
this document left out two of nine operations without a warning.

Do not hand the whole reference to docgen when the prose is the product. Its pages print routes
and SDK operations but left out all nine of the spec's summaries. A hand-built
mkdocs-material site is the better fit there.

Pick orval when your clients are query hooks, such as React Query's, since `docs.route` puts every
route on a TypeDoc page. Pick openapi-typescript with Redoc when readers call the HTTP API directly.

## Related how-tos

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

- [Handle endpoints that do not map to an entity](/howto/endpoints-that-map-to-no-entity)

- [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)

## Last verified

Verified 2026-11-22 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, sdkgen 4.44.3, apidef
8.32.4 and docgen 0.30.9, and once against sdkgen 4.45.0 with apidef 8.33.1. Redocly CLI 2.82.0,
orval 8.48.0 with TypeDoc 0.28.20, and openapi-typescript 7.13.0 ran in `record.sh`, and their
output is not committed. mkdocs-material was not run.

[^1]: The [README](https://github.com/voxgig/docgen/blob/v0.30.9/README.md) also records how the
site came to be shaped this way. It says the refactor replaces `docs/apidocs`, and that a project
built before it must drop that docs index include and install editions. The package on npm ships a
shorter README that points to this one, so the apidocs line is in the repository only.

[^2]: In [OpenAPI 3.0.3](https://spec.openapis.org/oas/v3.0.3#operation-object), an empty
`security` array is how an operation removes the top-level security declaration. apidef's
[`authExchangeOp`](https://github.com/voxgig/apidef/blob/v8.32.4/ts/src/utility.ts#L1447) asks for
that empty array in a document secured by default, a POST, and a 200 or 201 JSON body with a field
such as `access_token`. All four held for this endpoint, and the probe removed only the first.