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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| docgen github-pages edition | 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 | 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 | 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 | 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 | 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
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.
Related how-tos
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
-
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 -
In OpenAPI 3.0.3, an empty
securityarray is how an operation removes the top-level security declaration. apidef’sauthExchangeOpasks for that empty array in a document secured by default, a POST, and a 200 or 201 JSON body with a field such asaccess_token. All four held for this endpoint, and the probe removed only the first. ↩︎ Back to text