How-to › Describe your API

How to check a spec will generate a usable client before merging#

Gate a pull request on readiness rules, an apidef entity model, and a diff of the generated client, to catch a renamed method that lint and validation pass.

Audience
API producer
Level
intermediate
Topic
Lint and govern API specs
Languages
TypeScript and Go
Verified

Read first: Gate a pull request on OpenAPI lint results

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
@voxgig/apidef model extractionAn entity-shaped client, where an operation on no entity falls outside itA soft failure by design: three of the four broken documents here built with ok: trueYou need a hard parse or reference error
Hey APIA TypeScript client generated in the same job as the checkIts validator is experimental, and it skipped the dangling $ref with exit 0You need a check that fails on a bad reference
OpenAPI Generator validate and generateAny of its client languages, with Java on the CI runnerA JVM start per run, and a renamed operation is only a log warningYour generator is another tool, whose output is what ships
Spectral readiness rulesShape rules you run on every commit, before any generatorCompares operationIds as written, so list_books beside listBooks passesThe 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.

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

  1. The Spectral rule reference explains operation-operationId-unique partly by noting that some SDK generators convert operationIds to method names. The rule compares the ids as they are written, so listBooks and list_books pass 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

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.