Your document has POST /things/search, which takes a filter and answers an array of things.
@voxgig/apidef 8.32.4 files it in the create slot of the thing entity, the slot
POST /things gets, with search as an action. The model a generator reads from then says that
searching creates a thing.
What you get
You will end up with a table that gives every operation’s operationId, method, path, and the kind apidef chose, and a guide correction for the wrong ones. This is for you if you generate from a model and want to read its guesses first.
Short answer
Run @voxgig/apidef as a library over the document and print one row per operation:
operationId, method, path, and the entity and slot it landed in. The model drops operationId,
so join it back by method and path. apidef has six slots: list, load, create, update,
remove and patch. Fix a wrong guess in the guide file, pin the apidef version, and read the
table again after every upgrade.
You will need
Node 22 or later and an OpenAPI 3 document. Verified 2026-11-22 against @voxgig/apidef 8.32.4,
and again on 8.33.1. The sample document has eleven operations on six paths: /things, its item path, a
search, an archive action, /health and /reports/{reportId}.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| @voxgig/apidef heuristics | Hundreds of operations, and SDKs shaped as entities with list, load and create | Guesses that move between releases, and a guide file to correct the wrong ones | Method names must be exactly what the document’s authors wrote |
| Kiota request builders | A client that mirrors the URL tree, one request builder per path segment | No kinds at all: a search is a POST on its own path, named by the method | Callers expect list, load and create on an entity |
| NSwag operation generation modes | C# or TypeScript clients whose operationIds already read Things_List | The mapping lives in every operationId, written and kept by people | The operationIds follow no convention and cannot change |
| OpenAPI Generator operationId methods | Method names should be the operationIds, grouped into classes by tag | No kind for any operation, and untagged ones share one DefaultApi class | The generator should group operations into entities for you |
Voxgig maintains apidef. It is the subject of this page, and its row says what the heuristics cost; the other three tools are not Voxgig’s.
Heuristics scale to a document nobody has read in full, and they get some operations wrong. The operationId conventions OpenAPI Generator and NSwag rely on are exact, and a person has to write and keep every one. Kiota avoids the question by naming nothing after a kind.
Print the kind of every operation
classify.mjs builds apidef’s model in memory, with ctrl.step.generate off so no model files
are written. The model keeps the method and path of each point and drops the operationId, so
the script joins each point back to the document.
const kinds = new Map()
for (const name of entities) {
for (const [slot, op] of Object.entries(kit.entity[name].op ?? {})) {
for (const point of op?.points ?? []) {
const key = `${point.m} ${point.o}`
const kind = `${name}.${slot}` + (point.q?.$action ? ` (action ${point.q.$action})` : '')
kinds.set(key, kinds.has(key) ? `${kinds.get(key)}, ${kind}` : kind)
}
}
}
const rows = ops.map((o) => ({ ...o, kind: kinds.get(`${o.method} ${o.path}`) ?? 'none' }))
The rows come from the document, not the model. An operation the model leaves out still gets a
row, marked none.
node classify.mjs api.json
@voxgig/apidef 8.32.4
operationId method path kind
listThings GET /things thing.list
createThing POST /things thing.create
headThings HEAD /things none
getThing GET /things/{thingId} thing.load
replaceThing PUT /things/{thingId} thing.update
deleteThing DELETE /things/{thingId} thing.remove
patchThing PATCH /things/{thingId} thing.patch
searchThings POST /things/search thing.create (action search)
archiveThing POST /things/{thingId}/archive thing.create (action archive)
healthCheck GET /health health.load
fetchReport GET /reports/{reportId} thing.list
Read which signal decided each kind
The method decides the slot first. In 8.32.4, METHOD_IDOP in
dist/guide/heuristic01.js
(line 33) maps GET to load, POST to create, PUT to update, DELETE to remove, PATCH to
patch and HEAD to head. Line 1002 then turns a load into a list when the response is a
list, which is why fetchReport is not a load.
Two rules in
dist/transform/operation.js
come after that. Line 19 drops head, so HEAD lands on no slot.1 Line 113 moves patch into
update when the entity has no update. The path shape names the entity and turns a trailing
literal into an action, but it does not pick the slot: a GET on /things that answers one Thing
is a load.
shapes.mjs changes api.json one way at a time and prints the kind of the operation each change
is about, one row for each path shape.
node shapes.mjs
@voxgig/apidef 8.32.4
nothing: a collection GET /things thing.list
nothing: an item GET /things/{thingId} thing.load
nothing: an action after an item POST /things/{thingId}/archive thing.create (action archive)
GET /things answers one Thing GET /things thing.load
GET on the item answers an array GET /things/{thingId} thing.list
the item loses its PUT PATCH /things/{thingId} thing.update
a nested collection is added GET /things/{thingId}/parts thing.list (action part)
GET / is added, no parameter, no noun GET / service_index.load
The nested collection became an action on thing, not an entity of its own. With no noun in the
path, the entity took its name from the operationId serviceIndex, although the model keeps no
operationId field. 8.33.1 printed the same eight kinds.
The request body changed no kind in this document. body-probe.mjs removes all four request
bodies and classifies again. The heuristics page does name rules that read a body. They name a command, or decide whether a
PUT to a sub-path updates the item, and this document gives neither case.
node body-probe.mjs
@voxgig/apidef 8.32.4: 4 request bodies removed, 0 of 11 kinds changed
Correct the search in the guide
apidef reads corrections from the guide entry file, below the two include lines. This one switches
off the create slot for the search path and puts it in list.
guide: entity: thing: path: "/things/search": op: create: { active: false, method: "POST" }
guide: entity: thing: path: "/things/search": op: list: method: "POST"
node classify.mjs api.json guide/search-is-a-list.aontu
@voxgig/apidef 8.32.4
operationId method path kind
listThings GET /things thing.list
createThing POST /things thing.create
headThings HEAD /things none
getThing GET /things/{thingId} thing.load
replaceThing PUT /things/{thingId} thing.update
deleteThing DELETE /things/{thingId} thing.remove
patchThing PATCH /things/{thingId} thing.patch
searchThings POST /things/search thing.list (action search)
archiveThing POST /things/{thingId}/archive thing.create (action archive)
healthCheck GET /health health.load
fetchReport GET /reports/{reportId} thing.list
The search row moved and the other ten did not, which a test checks. create keeps method: "POST"
inside the braces on purpose. The shorter op: create: active: false builds on 8.32.4 and stops
the 8.33.1 build, because 8.33.1 already puts the search in list and has no create there to
switch off. generate.sh ran both forms on 8.33.1.
--- with guide/search-is-a-list-bare.aontu
apidef 8.33.1 did not build: SUMMARY (1 errors): [aontu/mapval_spread_required]: Cannot unify values at path $.guide.entity.thing.path.op.method
exit 1
--- request bodies
@voxgig/apidef 8.33.1: 4 request bodies removed, 0 of 11 kinds changed
On 8.33.1 the uncorrected table differs in two rows: searchThings is thing.list (action search), and fetchReport gains (action report). 8.33.1 adds a rule after the method map: a
POST whose last literal opens with a read verb such as search, and that answers a collection, is
a list. The
classification heuristics page
on the main branch states that rule. So on 8.32.4 the search needs the correction, and on 8.33.1
it needs none and only the braced form builds. Pin the release in a lockfile, because the table
belongs to one version.
Check it worked
Run the tests. They pin all eleven kinds and every path shape on 8.32.4, both guide forms, the PATCH rule, the body probe, and the entity an operationId names. They also read the records from 8.33.1 and the two other generators.
node --test classify.test.mjs
# tests 19
# suites 0
# pass 19
# fail 0
# cancelled 0
# skipped 0
# todo 0
A correction has worked when its row reads thing.list (action search) and no other row moved.
When it goes wrong
The table is empty and the build reported success. apidef builds a document cut short after
"paths": and returns a model with no entity, and the test reproduces that. classify.mjs
parses the document with JSON.parse first, refuses a run that classified no operation, and
exits 1 for both.
The build fails after an upgrade with mapval_spread_required. A guide correction names a slot the
release no longer fills. Write the switched-off slot with its method, as guide/search-is-a-list.aontu
does, and run the table on both versions before you merge the upgrade.
An operation reads none. HEAD gives no slot in this run, and the heuristics page says the same
of OPTIONS and TRACE. Decide for each none whether the SDK needs it, and reach it some other
way if it does.
Name operations the way OpenAPI Generator and NSwag do
Neither run assigned a kind. OpenAPI Generator names each method after its operationId and
puts untagged operations in DefaultApi; the committed typescript-fetch client has exactly the
eleven operationIds. Given a tag on each operation, the same release wrote HealthApi,
ReportsApi and a ThingsApi holding nine methods. Its
--operation-id-name-mappings
option renames one method without editing the document.
NSwag’s OperationGenerationMode is the closer match, because one of its modes reads path shape.
Its settings page says
MultipleClientsFromPathSegments takes the operation name from the nth segment and the client name
from the one before it. In this run, the operations on /things and its item also got the HTTP
method.
node methods.mjs PathSegments
NSwag, MultipleClientsFromPathSegments
Client.thingsGet GET /things
Client.thingsPost POST /things
Client.thingsHead HEAD /things
Client.thingsGet GET /things/{thingId}
Client.thingsPut PUT /things/{thingId}
Client.thingsPatch PATCH /things/{thingId}
Client.thingsDelete DELETE /things/{thingId}
Client.health GET /health
Client.reports GET /reports/{reportId}
ThingsClient.search POST /things/search
ThingsClient.archive POST /things/{thingId}/archive
The list and the load are both thingsGet, and tsc refuses the file. NSwag 14.8.0 was the
newest release on npm on the day.
== path-segments.ts exit 2
generated/nswag/path-segments.ts(23,5): error TS2393: Duplicate function implementation.
The default mode, MultipleClientsFromOperationId, reads operationIds in the form
{controller}_{action}, and put all eleven of this document’s ids in one Client. Write the
classification into the ids, as controller-ids.mjs does, and NSwag groups the operations by
entity.
node methods.mjs controller
NSwag, {controller}_{action} ids
ThingsClient.list GET /things
ThingsClient.create POST /things
ThingsClient.head HEAD /things
ThingsClient.load GET /things/{thingId}
ThingsClient.update PUT /things/{thingId}
ThingsClient.patch PATCH /things/{thingId}
ThingsClient.remove DELETE /things/{thingId}
ThingsClient.search POST /things/search
ThingsClient.archive POST /things/{thingId}/archive
HealthClient.load GET /health
ReportsClient.list GET /reports/{reportId}
That client compiles. The search is ThingsClient.search, a name a person chose, so no heuristic
can file it under create.
When not to do this
Do not trust a classification you have not printed. apidef’s heuristics page says they are tuned for conventional REST APIs, and the table is where a wrong guess shows before an SDK ships.
Do not leave the apidef version floating. The same document gave two different tables on 8.32.4 and 8.33.1, and a correction written for one stopped the other’s build.
Do not use apidef for a small API whose operationIds you control. Writing Things_List by hand
for twenty operations is a short job, and NSwag or OpenAPI Generator then needs no correction
file and gives exactly the names you wrote. Kiota suits a team that wants its client to follow
the URL tree and not to name kinds at all.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5 and @voxgig/apidef 8.32.4, with 8.33.1 run by
generate.sh in a scratch copy. OpenAPI Generator 7.27.0, NSwag 14.8.0 on the ASP.NET Core 10
runtime, and TypeScript 5.9.3 also ran once there, and their output is committed. Every output
block is what the command preceding it printed. Kiota was not run; its row comes from its
documentation, read on the same day.
Footnotes
-
HEAD asks for what GET would return, minus the content, as RFC 9110 section 9.3.2 puts it, which leaves an entity model little to hold. PATCH has a definition of its own in RFC 5789, which tells it from PUT by the body. A PUT body is a modified version of the resource, and a PATCH body is a set of instructions for modifying it. ↩︎ Back to text