@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 -> [ { name:'id', type:'`$STRING`', req:true }, … ]

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

Documentation

Comprehensive docs live 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 reproduces it exactly. TypeScript is the source of truth; Go follows. See the parity explanation.

Build & test

npm run build      # tsc --build ts/src ts/test  ->  ts/dist, ts/dist-test
npm test           # node --test ts/dist-test/**/*.test.js
make all           # TypeScript build+test AND Go build+test

For AI coding agents

This repository ships agent-oriented context files: AGENTS.md, CLAUDE.md, and llms.txt. Start with AGENTS.md.

License

MIT