@voxgig/apidef

Voxgig SDK generator — turn an OpenAPI/Swagger spec into a structured API model.

@voxgig/apidef reads an OpenAPI 3 (or Swagger 2.0) specification and produces an internal API model: a normalized description of the entities, operations, fields, and flows implied by the spec. It infers the things OpenAPI leaves implicit — which paths form a resource, which methods are create/read/update/delete, how parameters map to identifiers — and emits an editable model that downstream tooling (notably sdkgen) turns into client SDKs.

OpenAPI / Swagger  ──▶  apidef  ──▶  entities · operations · fields · flows  ──▶  SDKs

Install

npm install @voxgig/apidef

Requires Node.js 24+. Several Voxgig libraries are peer dependencies (jostraca, aontu, jsonic, @jsonic/yaml, @voxgig/struct, @voxgig/util, shape); npm installs them automatically.

Quick example

const { ApiDef } = require('@voxgig/apidef')

const build = await ApiDef.makeBuild({ folder: '/proj/model', outprefix: 'petstore-' })

const result = await build(
  { name: 'petstore', def: 'petstore.yml' },   // model: name + spec file
  { spec: { base: '/proj/model' } },            // build: spec read from base/../def/
  {},
)

const entities = result.apimodel.main.kit.entity
// entities.pet.op -> { load, list, create, update, remove }
// entities.pet.fields -> { id: { n:'id', h:'Id', t:'`$STRING`', r:true }, … }

A full walk-through is in the getting-started tutorial.

Documentation

The documentation lives in docs/:

• Tutorial — learn by generating your first model.
• How-to guides — library · CLI · naming · pipeline control · debugging · contributing
• Reference — API · CLI · configuration · model · guide · pipeline
• Explanation — architecture · classification heuristics · the internal model · canonical build & parity port

Two implementations

apidef ships a canonical TypeScript implementation (ts/, the published package) and a Go parity port (go/) that follows it. TypeScript is the source of truth; Go follows, and shared fixtures pin what the two share. See the parity explanation.

Build & test

cd ts && npm run build   # tsc --build src test  ->  ts/dist, ts/dist-test
cd ts && npm test        # node --test dist-test/**/*.test.js
make all                 # TypeScript build+test AND Go build+test (from repo root)

The npm package lives in ts/; run npm there. go/ is the parallel Go project. make all from the repo root drives both, and make test also runs the prose gate over these pages, which follow the style guide.

License

MIT