A pull request adds a books list under shelves to your OpenAPI document. Its operationId,
list_books, is unique, so lint passes and validation passes.1 In the regenerated TypeScript
client, listBooks now calls /shelves/{shelfId}/books and requires a shelf id, so every
caller that listed books breaks at the next release.
What you get
You will end up with a pre-merge check that runs readiness rules, builds an entity model with apidef, and diffs the generated client’s public surface against the base branch. This is for you if a generated client ships from the document you review.
Short answer
Run readiness rules, then generate the client and diff its public surface against the base
branch. Rules catch a missing operationId, a response without a schema, and a $ref that
resolves to nothing. @voxgig/apidef finds operations that land on no entity, but built a split
document and a cut one with ok: true, so fail on zero entities. Only the surface diff caught
listBooks moving to another path.
You will need
Node 22 or later, an OpenAPI 3 document in JSON, and the generator your team ships with. Gate the
document on lint first, as
Gate a pull request on OpenAPI lint results shows.
make-specs.mjs writes the documents here: base.json for the base branch, pr.json for the
pull request, and four broken ones. These are a dangling $ref, paths split into other files,
and two copies cut after "paths": , one with a newline at the end and one without. pr.json adds the shelves list at the top of paths, a
reviews list, and a HEAD /books.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| @voxgig/apidef model extraction | An entity-shaped client, where an operation on no entity falls outside it | A soft failure by design: three of the four broken documents here built with ok: true | You need a hard parse or reference error |
| Hey API | A TypeScript client generated in the same job as the check | Its validator is experimental, and it skipped the dangling $ref with exit 0 | You need a check that fails on a bad reference |
| OpenAPI Generator validate and generate | Any of its client languages, with Java on the CI runner | A JVM start per run, and a renamed operation is only a log warning | Your generator is another tool, whose output is what ships |
| Spectral readiness rules | Shape rules you run on every commit, before any generator | Compares operationIds as written, so list_books beside listBooks passes | The question is what a generator makes of the names |
Voxgig maintains apidef. It is one of four options here, not the recommendation.
Rules are fast and see shape only. OpenAPI Generator’s validate failed the dangling and the two
cut documents and passed the split one, and its generate run warned about the rename without
failing. Hey API generated from every document but the two cut ones. apidef answers a different question, where
each operation lands, and needs a zero-entity check of your own.
Run the readiness rules and the model
ready.mjs parses the document as strict JSON and runs four rules. Every operation has an
operationId that stays distinct once case and punctuation are dropped. Every 2xx
response has a schema, except a 204 or the answer to a HEAD, and every request body names a media type. Every $ref is
local and resolves. It then builds the apidef model on the release pinned in package-lock.json:
const m = await model(specPath)
const names = Object.keys(m.entity).sort()
if (!m.ok) found.push(`apidef: build failed, ${String(m.err?.message ?? m.err).split('\n')[0].replace(/\x1b\[[0-9;]*m/g, '').trimEnd()}`)
else if (names.length === 0) found.push('apidef: zero entities')
if (m.warnings) found.push(`apidef: ${m.warnings} warnings`)
if (doc && typeof doc === 'object' && m.ok) {
const placed = new Set()
for (const e of Object.values(m.entity)) {
for (const op of Object.values(e.op ?? {})) for (const p of op?.points ?? []) placed.add(`${p.m} ${p.o}`)
}
for (const { method, path } of operations(doc)) if (!placed.has(`${method} ${path}`)) found.push(`apidef: ${method} ${path} is on no entity`)
}
return { entities: names, found }
Run it on all five documents:
node ready.mjs specs/base.json specs/pr.json specs/dangling.json specs/truncated.json specs/truncated-newline.json specs/split/openapi.json
specs/base.json: ok, apidef entities: book
specs/pr.json: FAIL, apidef entities: book, review
GET /books: operationId listBooks folds to the same name as list_books
apidef: HEAD /books is on no entity
specs/dangling.json: FAIL, apidef entities: bok, book
$.paths./books/{bookId}.get.responses.200.content.application/json.schema: $ref #/components/schemas/Bok resolves to nothing
specs/truncated.json: FAIL, apidef entities: none
not valid JSON: Unexpected end of JSON input
apidef: zero entities
specs/truncated-newline.json: FAIL, apidef entities: none
not valid JSON: Unexpected end of JSON input
apidef: build failed, @voxgig/apidef: parse: internal: [jsonic/unexpected]: unexpected character(s):
apidef: 1 warnings
specs/split/openapi.json: FAIL, apidef entities: none
no operations under paths
$.paths./books: external $ref ./paths/books.json, bundle the document first
$.paths./books/{bookId}: external $ref ./paths/books-bookId.json, bundle the document first
apidef: zero entities
The script exits 1 on any finding. The HEAD /books line is the apidef signal: an operation the
entity model has no slot for, which an entity-shaped client reaches only through its escape
hatches, if at all.
Read what apidef reports on its own
apidef is built to fail soft, as its
debugging guide says,
recording a warning and building as much as it can. alone.mjs prints what the build itself
reports:
node alone.mjs specs/base.json specs/pr.json specs/dangling.json specs/truncated.json specs/truncated-newline.json specs/split/openapi.json
apidef 8.32.4
document build ok entities warnings operations on an entity
specs/base.json true book 0 4 of 4
specs/pr.json true book,review 0 6 of 7
specs/dangling.json true bok,book 0 4 of 4
specs/truncated.json true none 0 0 of unparsed
specs/truncated-newline.json false none 1 0 of unparsed
specs/split/openapi.json true none 0 0 of 0
The copy cut after "paths": with no newline at the end built with ok: true, zero entities and
no warning, as did the one whose paths live in other files. The same cut with a newline at the end
failed with one warning, and apidef wrote apidef-warnings.txt into the working directory, where
a later clean build leaves it. The misspelled $ref to Bok produced an entity named bok,
which took the list, create, and remove operations from book. record.sh ran the same six on
apidef 8.33.1, the newest release, and got the same table.
Generate both clients and diff the surface
record.sh ran OpenAPI Generator’s typescript-fetch and Hey API on base.json and pr.json,
and committed each client’s operations file, with Hey API’s types.gen.ts beside it. surface.mjs
reads either kind and lists each callable with its method, path, and request type. It also lists
the members of that type, read from the same file or from the file it is imported from:
node surface.mjs generated/openapi-generator-base.ts generated/openapi-generator-pr.ts
~ listBooks GET /books (none) -> GET /shelves/{shelfId}/books (ListBooksRequest { shelfId: string })
+ headBooks HEAD /books (none)
+ listBookReviews GET /books/{bookId}/reviews (ListBookReviewsRequest { bookId: string })
+ listBooks_1 GET /books (none)
4 changes, 1 that break a caller
node surface.mjs generated/hey-api-base/sdk.gen.ts generated/hey-api-pr/sdk.gen.ts
~ listBooks GET /books (optional ListBooksData { body?: never; path?: never; query?: never; url: '/books' }) -> GET /shelves/{shelfId}/books (required ListBooksData { body?: never; path: { shelfId: string }; query?: never; url: '/shelves/{shelfId}/books' })
+ listBooks2 GET /books (optional ListBooks2Data { body?: never; path?: never; query?: never; url: '/books' })
+ headBooks HEAD /books (optional HeadBooksData { body?: never; path?: never; query?: never; url: '/books' })
+ listBookReviews GET /books/{bookId}/reviews (required ListBookReviewsData { body?: never; path: { bookId: string }; query?: never; url: '/books/{bookId}/reviews' })
4 changes, 1 that break a caller
Both generators gave the first operation in paths the name listBooks, and the existing call
became listBooks_1 or listBooks2. OpenAPI Generator’s log said only
generated unique operationId listBooks_0, a third spelling, and both runs exited 0. Hey API’s
parser options say a detected
error exits the tool when validate_EXPERIMENTAL is on, yet with it on the dangling $ref only
logged Skipping unresolvable $ref and the client was written. The diff
exits 1 on a removal or a changed signature, so it is the line that blocks the merge. A changed
signature includes a request member whose type changes, that becomes required, or that goes away,
under the same type name. The diff compares member text only. It does not follow a type a member
names, so a change inside Book passes.
Check it worked
check.test.mjs holds 17 tests over the findings, the records, and the surface diffs. Each
readiness rule fails a document that breaks only that rule, and an empty or a missing document
fails. Each client’s diff fails a request member that changes type, becomes required, or goes
away, and passes an unchanged client. A probe of apidef alone shows the stray apidef-warnings.txt
that the gate keeps out of the working directory.
node --test check.test.mjs
1..17
# tests 17
# suites 0
# pass 17
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 3628.739489
When it goes wrong
The gate passes a document that no longer describes the API. apidef built a split document as zero
entities and reported ok: true. Bundle multi-file documents before the check, as
Split and bundle a large OpenAPI document does, and
keep the zero-entity rule.
A stray apidef-warnings.txt appears in the repository. apidef writes it to the working directory
of any build with warnings, such as the cut copy with a newline, and a later clean build leaves it
there. ready.mjs resolves the path, then builds in a scratch directory, so the file never lands.
The surface diff throws no operations found. The patterns in surface.mjs read
typescript-fetch’s DefaultApi.ts and Hey API’s sdk.gen.ts only. Point it at those files, or
add a pattern for your generator’s output, rather than letting an empty surface pass.
The surface diff prints request type not found and exits 1. It found a callable but not the
declaration of its request type. Keep Hey API’s types.gen.ts beside sdk.gen.ts, because the
diff reads the type from the file the import names.
When not to do this
Do not use apidef as a validator. It reported ok: true on three of the four broken documents
here, so pair it with strict parsing and reference checks, as ready.mjs does.
Do not gate on generator exit codes. OpenAPI Generator exited 0 on the rename, and Hey API exited
0 on the dangling $ref with validate_EXPERIMENTAL on.
Do not run a generation job on every commit of a draft. It costs a JVM or an npm install per run, while the rules need neither, and the surface diff matters once a release is near.
OpenAPI Generator is the better gate when you ship clients in several of its languages, because
one validate covers them all. Hey API suits a TypeScript-only team that already generates in CI.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, @voxgig/apidef 8.32.4 and 8.33.1, OpenAPI Generator
7.27.0, @hey-api/openapi-ts 0.99.0 with TypeScript 5.9.3, and Spectral 6.17.1. Every output block
is what the command preceding it printed. The apidef checks run on each build. OpenAPI Generator,
Hey API, Spectral and apidef 8.33.1 ran once in record.sh, and their records and the two clients’
operation files are committed. Hey API’s two types.gen.ts files came from a later run of 0.99.0
on the same documents, whose sdk.gen.ts matched the committed files byte for byte. Spectral ran with SCARF_ANALYTICS=false, which opts out of the
install-time telemetry of its @scarf/scarf dependency.
Footnotes
-
The Spectral rule reference explains
operation-operationId-uniquepartly by noting that some SDK generators convert operationIds to method names. The rule compares the ids as they are written, solistBooksandlist_bookspass it. Both generators on this page converted the two to the same method name, and then put a suffix on one of them. ↩︎ Back to text