# 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.

Source: https://voxgig.com/howto/check-a-spec-generates-a-usable-client

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

## 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](/howto/gate-a-pull-request-on-openapi-lint) 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](https://github.com/voxgig/apidef/blob/main/docs/how-to/debug-a-build.md) | 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](https://heyapi.dev/docs/openapi/typescript/configuration/parser) | 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](https://openapi-generator.tech/docs/usage/#validate) | 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](https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md) | 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`:

```js title="ready.mjs"
  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:

```bash
node ready.mjs specs/base.json specs/pr.json specs/dangling.json specs/truncated.json specs/truncated-newline.json specs/split/openapi.json
```

```text output
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](https://github.com/voxgig/apidef/blob/main/docs/how-to/debug-a-build.md) says,
recording a warning and building as much as it can. `alone.mjs` prints what the build itself
reports:

```bash
node alone.mjs specs/base.json specs/pr.json specs/dangling.json specs/truncated.json specs/truncated-newline.json specs/split/openapi.json
```

```text output
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:

```bash
node surface.mjs generated/openapi-generator-base.ts generated/openapi-generator-pr.ts
```

```text output
~ 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
```

```bash
node surface.mjs generated/hey-api-base/sdk.gen.ts generated/hey-api-pr/sdk.gen.ts
```

```text output
~ 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](https://heyapi.dev/docs/openapi/typescript/configuration/parser) 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.

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

```text output
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](/howto/split-and-bundle-an-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

- [Gate a pull request on OpenAPI lint results](/howto/gate-a-pull-request-on-openapi-lint)

- [Detect breaking changes between two OpenAPI versions in CI](/howto/detect-breaking-changes-between-openapi-versions-in-ci)

- [Split and bundle a large OpenAPI document](/howto/split-and-bundle-an-openapi-document)

- [Enforce a naming convention across 40 microservice specs](/howto/enforce-naming-conventions-across-many-specs)

- [Regression test model extraction in CI](/howto/regression-test-model-extraction-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.

[^1]: The Spectral [rule reference](https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md)
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.