# How to generate a provider plugin from an OpenAPI document

> Add the seneca-provider target to an sdkgen project, generate a Seneca plugin from a vendor OpenAPI document, and guard the commands the API lacks.

Source: https://voxgig.com/howto/generate-a-provider-plugin-from-openapi

- Audience: api-consumer
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

Scaffold an sdkgen project from the vendor's OpenAPI document with the ts target, install @voxgig/sdkgen-infrapack, run voxgig-sdkgen package add to bring in the seneca-provider target, and generate. The plugin exposes each entity in the model as provider/<vendor>/<entity>. Read the model first, and refuse the Seneca commands the API has no operation for, which seneca-entity otherwise answers from memory.

---
## You will need

Node 22 or later, the vendor's OpenAPI 3 document, and a Seneca service with seneca-entity
and `@seneca/provider`. Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, @voxgig/sdkgen-infrapack 0.0.20, and Seneca 3.38.0.
The document here, `vendor.json`, describes an invented carrier, `parcelpoint` in every generated name, with shipments,
tracking events, a cancel route, and a quote route, behind an `X-Api-Key` header. The
[seneca-entity README](https://github.com/senecajs/seneca-entity) covers the entity API the plugin
speaks.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [NSwag](https://github.com/RicoSuter/NSwag/wiki/TypeScriptClientGenerator) | You already generate NSwag clients for C# and want one toolchain | A hand-written plugin over its client, and the key added through your own fetch | The vendor changes its document often |
| [OpenAPI Generator `typescript-fetch`](https://openapi-generator.tech/docs/generators/typescript-fetch/) | You want its typed `Api` classes and wide option set | A Java runtime to generate, and the entity mapping written by hand | You would rather not run Java in the build |
| [`openapi-typescript` with `openapi-fetch`](https://openapi-ts.dev/openapi-fetch/) | You want control of each call, with paths checked by TypeScript | Every entity, command, and 404 rule written and updated by hand | The vendor's document grows by several operations a release |
| [sdkgen seneca-provider target](https://github.com/voxgig/sdkgen-infrapack) | The vendor's document classifies into entities, and you regenerate on each release | A second package to install, and a guard for commands the API lacks | The vendor's operations are actions rather than resources |

Voxgig maintains sdkgen and the package that adds this target. It is the subject of this page,
and the last column of its row says when to pick something else.

The trade-off is regeneration against control. The generated plugin follows the vendor's
document on every run, but its shape is whatever the model made of that document. The
hand-written plugins over NSwag or openapi-fetch take 41 and 45 lines here and decide every
operation themselves, so each vendor change is yours to port.

## Generate the provider from the vendor's document

`seneca-provider` is not bundled with sdkgen. It ships in `@voxgig/sdkgen-infrapack`, which
[sdkgen's out-of-tree targets page](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/out-of-tree-targets.md)
says to add with `package add`. The target wraps the `ts` SDK, so scaffold with `--target ts`
first.

```bash title="generate.sh"
npx --yes @voxgig/create-sdkgen@0.31.9 parcelpoint --def vendor.json --target ts
cd parcelpoint-sdk/.sdk
npm install --save-dev @voxgig/sdkgen-infrapack@0.0.20
npx voxgig-sdkgen package add @voxgig/sdkgen-infrapack --only target:seneca-provider
npm run generate
```

`package add` reported that it added the target `seneca-provider`, and `npm run generate` wrote the plugin to
`parcelpoint-sdk/seneca-provider/` beside `ts/`. That folder is the default while
`main: kit: target: 'seneca-provider': output: path` is unset. Set that key in
`.sdk/model/project.aontu` to generate into the provider's own repository.

The generated package is `@seneca/parcelpoint-provider`, and it depends on
`@voxgig-sdk/parcelpoint-sdk`, the SDK from the same run. Neither is on npm, so `generate.sh`
builds the SDK and installs it into the provider by path. The generated `package.json` declares
Node 24 or later, and everything here ran on Node 22.

## Read the model before you trust the plugin

Every Seneca command in the plugin comes from the entity model apidef extracted. `model.cjs` reads
it from the compiled SDK that the plugin calls through.

```bash
node model.cjs
```

```text output
quote (id field: no)
  create  POST /quote
  no list, no load, no remove, no update
shipment (id field: yes)
  create  POST /shipments/{shipmentId}/cancel  (action$: cancel)
  create  POST /shipments
  list    GET  /shipments
  load    GET  /shipments/{shipmentId}
  no remove, no update
tracking_event (id field: yes, under shipment)
  list    GET  /shipments/{shipmentId}/events
  no create, no load, no remove, no update
```

Two operations did not classify as resources. `POST /quote` became an entity, `quote`, with no
id field, so pricing a parcel is a `save$` on `provider/parcelpoint/quote`. The cancel route is a
second point of the shipment's create, reached with an `action$` directive, as the
infrapack README describes. On this document, every
operation landed on some entity, so none was left for the SDK's `direct()` call.

## Load the plugin and call the vendor

The plugin takes its key from the `keymap` of `@seneca/provider` and hands it to the SDK, which sends it
as `X-Api-Key`, as `vendor.json` declares. `seneca.cjs` sets up Seneca the way the generated
README does, except that it passes the key as a literal where the README reads
`$PARCELPOINT_APIKEY` through `@seneca/env`.

```js title="seneca.cjs"
async function makeSeneca(plugin, pluginopts, key) {
  const seneca = Seneca({ legacy: false })
    .quiet()
    .use('promisify')
    .use('entity')
    .use('provider', { provider: { parcelpoint: { keys: { apikey: { value: key } } } } })
    .use(plugin, pluginopts)
  await seneca.ready()
  return seneca
}
```

`sandbox.cjs` stands in for the vendor's sandbox on 127.0.0.1. It answers the six operations in
`vendor.json` and nothing else, and refuses a request without the key.

```bash
node demo.cjs
```

```text output
loaded parcelpoint provider 0.0.1, sdk @voxgig-sdk/parcelpoint-sdk 0.0.1
list$  -> 2 provider/parcelpoint/shipment: shp_1 in_transit, shp_2 created
load$  -> shp_1 ORD-1001 in_transit
events -> PICKED_UP, IN_TRANSIT
save$  -> shp_3 created
cancel -> shp_3 cancelled

requests the sandbox received:
  GET  /v2/shipments                X-Api-Key ok
  GET  /v2/shipments/shp_1          X-Api-Key ok
  GET  /v2/shipments/shp_1/events   X-Api-Key ok
  POST /v2/shipments                X-Api-Key ok
  POST /v2/shipments/shp_3/cancel   X-Api-Key ok
```

The cancel is `make$({ id }).directive$({ action$: 'cancel' }).save$()`. A `list$` without a
`shipment_id` on `tracking_event` throws before any request, because the path needs the parent.

## Write the same provider over NSwag or openapi-fetch

Neither NSwag nor openapi-fetch has a Seneca target, so both routes end in a plugin you write with
`@seneca/provider`'s `entityBuilder`. NSwag's `openapi2tsclient` wrote a `Client` class with one
method per operation. Its constructor falls back to `window` when given no `http` object, which
throws in Node, so pass one that adds the key.

```js title="nswag-provider.cjs"
  this.prepare(async function () {
    const res = await this.post('sys:provider,get:keymap,provider:parcelpoint')
    const key = res.keymap.apikey.value
    // The client NSwag wrote for vendor.json sends no X-Api-Key, so the header goes on here.
    const http = { fetch: (url, init = {}) => fetch(url, { ...init, headers: { ...init.headers, 'X-Api-Key': key } }) }
    this.shared.client = new Client(options.base, http)
  })
```

[openapi-fetch](https://openapi-ts.dev/openapi-fetch/api) takes `baseUrl` and `headers` in
`createClient`, and its calls name the path as the document spells it, such as
`client.GET('/shipments/{shipmentId}', { params: { path: { shipmentId } } })`. The types that
[openapi-typescript](https://openapi-ts.dev/introduction) generated check those paths in a
TypeScript build. `compare.cjs` makes the same calls through all three plugins.

```bash
node compare.cjs
```

```text output
plugin                   list$  load$ shp_1   load$ missing  events  lines you write
sdkgen seneca-provider   2      in_transit    null           2       0
NSwag client, by hand    2      in_transit    null           2       41
openapi-fetch, by hand   2      in_transit    null           2       45
```

Both hand-written plugins check each id with `segment.cjs`. NSwag and openapi-fetch both encode
an id with [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent), which leaves `..` intact, and a test shows both requests reaching
`/v2/` itself.[^1] The generated SDK refuses `.` and `..` before sending.

## Check it worked

```bash
node --test provider.test.cjs
```

```text output
1..18
# tests 18
# suites 0
# pass 18
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

The suite loads the plugin, lists shipments through the sandbox with the key, and expects a 401
with a wrong one. It books and cancels a shipment, runs the plugin offline in the SDK's test mode,
and holds both hand-written plugins to the same calls.

## When it goes wrong

A `remove$` returns `null`, and the shipment is still there. The API has no remove, so the plugin
registers none, and seneca-entity hands the command to its default store, `mem-store`.[^2]
The generated `doc/reference.md` says such a canon has no `remove$`, which is true of the plugin
but not of the Seneca instance around it. `guard.cjs`, loaded after the plugin, refuses every
command the model has no operation for.

```bash
node pitfall.cjs
```

```text output
generated provider alone
  remove$('shp_2')                   returned null, sandbox got nothing
  load$, edit, save$                 returned shp_3, sandbox got POST /v2/shipments
  quote list$()                      returned [0], sandbox got nothing
  sandbox shipments with reference ORD-1001: shp_1, shp_3

with guard.cjs
  remove$('shp_2')                   threw: provider/parcelpoint/shipment remove$: the API has no remove operation
  load$, edit, save$                 threw: provider/parcelpoint/shipment save$: the record has an id and the API has no update, so save$ would book another
  quote list$()                      threw: provider/parcelpoint/quote list$: the API has no list operation
  sandbox shipments with reference ORD-1001: shp_1
```

A loaded shipment saved again books a second one. The API has no update, so `save$` always
creates, which the generated `doc/reference.md` states. The guard refuses a plain `save$` of a
record with an id and lets an `action$` through.

An entity's canon changes after an upgrade with no change to the document. With
`@voxgig/sdkgen` 4.45.0 and `@voxgig/apidef` 8.33.1, the events entity is named `event`, so
`provider/parcelpoint/tracking_event` falls through to `mem-store` and lists nothing. The guard
refuses any canon of the vendor that the model does not hold, so the old name throws instead. Pin
the generator's versions, and diff the model on every upgrade.

## When not to do this

Do not generate a provider for a vendor whose API is a set of actions. The model files them under
whatever entity fits, as `quote` shows, and callers then `save$` a price.

Do not deploy the sdkgen provider without a guard, or tests, for the commands its API lacks.
`mem-store` answers them, and the caller sees success.

Do not choose sdkgen to wrap a vendor that changes its document once a year. A 45-line plugin over
openapi-fetch is smaller than an sdkgen project, an SDK, and a second package. Pick NSwag when
your team already generates its C# clients and reviews its output. Pick OpenAPI Generator when
its options cover a client feature you need and Java is already in the build.

## Related how-tos

- [Migrate a hand-written vendor client to a provider plugin](/howto/migrate-a-vendor-client-to-a-provider)

- [Map vendor error responses onto message errors](/howto/map-vendor-errors-onto-message-errors)

- [Switch vendors behind one provider interface](/howto/switch-vendors-behind-one-provider-interface)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

## Last verified

Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
@voxgig/apidef 8.32.4, @voxgig/sdkgen-infrapack 0.0.20, Seneca 3.38.0, seneca-entity 28.1.0,
`@seneca/provider` 4.0.0, NSwag 14.8.0, openapi-typescript 7.13.0, and openapi-fetch 0.17.0. Every
output block is what the command preceding it printed. `generate.sh` ran once, and its output is
committed under `generated/`, including one model step with @voxgig/sdkgen 4.45.0 and
@voxgig/apidef 8.33.1. The generated suite passed 13 of its 14 tests after the same commands. The
fourteenth, `maintain`, reads the plugin's `.git/config` and wants a `main` branch in it, which a
scratch folder lacks. NSwag ran once on the ASP.NET Core 10 runtime.
OpenAPI Generator was not run; its row comes from its documentation. The vendor sandbox is a local
stand-in.

[^1]: [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html) puts the full stop among the
unreserved characters, which need no percent-encoding, and its section 5.2.4 removes `.` and `..`
segments when a reference is resolved. `encodeURIComponent` follows the first rule and the URL
parser inside fetch follows the second. An id of `..` therefore reaches the parent path, by two
rules that are each correct.

[^2]: The [seneca-entity README](https://github.com/senecajs/seneca-entity) says the default store,
`@seneca/mem-store`, is installed with the package. It also says the package is named
`@seneca/entity` from 29.0.0, and npm answered 404 for that name on the day this page was verified.
The generated plugin declares `seneca-entity` as a peer, and npm installed 28.1.0 for it in the generated project.