How-to › Document and support developers

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.

Audience
API producer
Level
intermediate
Topic
Publish reference docs
Languages
TypeScript
Verified

Your reference site has a page for book and a page for health, but no page tells a customer how to check that a book exists. The spec declares HEAD /books/{bookId} and a token exchange. The model the site is built from holds neither, so no generated page mentions them and the build finishes without a warning.

What you get

You will end up with a docgen site whose pages follow the SDK’s entities, and a check that fails when an operation in the spec reaches no page. This is for you if you generate an SDK with sdkgen and publish its reference from the same run.

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 check. docgen is the documentation companion to sdkgen, and its README is, by its own account, the full documentation.1

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
docgen github-pages editionAn sdkgen project, and a reference that names the SDK call beside each routeA scaffold and a generate step, and the operations the model drops are missing until you write themYou do not generate the SDK with sdkgen
hand-built mkdocs-materialReference and guides where the prose matters more than coverageA person writes every page and keeps it in step, on a Python toolchainThe API changes faster than anyone edits pages
openapi-typescript and openapi-fetchTyped TypeScript calls keyed by the spec’s own pathsIt writes types, never pages, so the site comes from another toolYou want pages from the same run as the client
orval docs with TypeDocAn orval client whose readers want a page per generated functionTypeDoc and its markdown plugin as dependencies, and a route on a page only for query hooksYour client is fetch-based and readers look up routes
Redoc through Redocly build-docsOne HTML file that shows the spec exactly as writtenThe spec’s own tags and order with no entity model, and paths drawn by a scriptReaders 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 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:

grep -E '^(editions|files in the docgen|WARN)' records/newest-release.txt
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:

node check-site.mjs api.json generated/docs --skip additional
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). Answer 204 with no body and the same release makes a book_archive entity, after a test whose source comment reads No response at all means not an action. apidef 8.33.1 takes the resource before a verb whatever the answer. Handle endpoints that do not map to an 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, and its heuristic switches off an entity whose only operations are token exchanges, marking it auth-exchange.

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

grep -E '^==|archive|token\.|identical' records/probe-a.txt
== 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.

# 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.
node check-site.mjs api.json generated/docs
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.

node --test check-site.test.mjs
# 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 says also turns off telemetry in the pages build-docs writes.

cat records/compare.txt
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 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. 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 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.

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.

Footnotes

  1. The README 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. ↩︎ Back to text

  2. In OpenAPI 3.0.3, an empty security array is how an operation removes the top-level security declaration. apidef’s authExchangeOp 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. ↩︎ 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.