# Voxgig SDK toolchain documentation

> Documentation for the Voxgig SDK toolchain: apidef turns a spec into a model, sdkgen turns the model into SDKs, and create-sdkgen scaffolds a project. Every example is taken from a public SDK the toolchain generated, so it can be checked rather than trusted. Checked 8 September 2026.

## The pipeline

1. **Describe** by your OpenAPI 3 or Swagger 2 spec, producing the API as its authors wrote it, paths and schemas.
2. **Model** by apidef, producing entities, operations, fields and flows, with the guide that records why.
3. **Shape** by you, editing the model, producing the SDK surface you actually want: names, types, which operations exist.
4. **Generate** by sdkgen, producing one SDK per target language, plus a CLI, an MCP server and generated docs.
5. **Verify** by the generated offline suites, producing tests that run with no server and no credentials.

The split matters when something is wrong. If the SDK exposes the wrong shape, the fix is in the model, and usually in apidef's guide. If the shape is right and the code is wrong, the fix is in a template or a component. Generated target code is never the place to fix either: a resync of the vendored target reverts hand edits, and `voxgig-sdkgen doctor` reports what a resync would take back.

## The components

- [sdkgen](https://voxgig.com/sdk/docs/sdkgen): Turns the model into SDKs. The generator. It reads the model apidef produced and writes one idiomatic SDK per target language, each with the same operation pipeline, the same feature set, generated documentation and an offline test suite.
- [apidef](https://voxgig.com/sdk/docs/apidef): Turns a spec into a model. The front half. It reads an OpenAPI 3 or Swagger 2 spec and produces an internal model of entities, operations, fields and flows, inferring what the spec leaves implicit and recording why it decided each thing.
- [create-sdkgen](https://voxgig.com/sdk/docs/create-sdkgen): Scaffolds a project. The way in. One command turns an OpenAPI spec into a project with the model already built, the targets you asked for already added, and a generate script wired up. Start here unless you are working on the toolchain itself.
- [docgen](https://voxgig.com/sdk/docs/docgen): Generates documentation targets. An sdkgen package rather than a separate tool. sdkgen defines a `docs` kind, a target whose destination is a documentation system rather than a language; docgen supplies the items for it.
- apigen: Not yet published. A repository exists and nothing is published from it. It is listed here so the shape of the toolchain is honest about what is real, and it will get a page when there is something to document.

## The worked examples

Two public SDKs, picked to be complementary rather than redundant.

### solardemo

A generated SDK for the Solar System API. Breadth. Two entities and a nested one, generated into every target the toolchain has, so it is the repository to read when the question is what a given language's output looks like.

- Entities: Planet, Moon, nested under Planet
- Targets: every bundled target, plus the CLI, the MCP server, the data package and the Seneca provider
- Features: secrets, test
- Source: https://github.com/voxgig-sdk/voxgig-solardemo-sdk

### elementdemo

A generated SDK for the Periodic Table API. Depth. Four entities, a server URL templated on a variable, five features including one this project wrote itself, and five targets. It is the repository to read when the question is how far the model can be pushed.

- Entities: Element, Group, Series, Isotope, nested under Element
- Targets: TypeScript, Python, Go, Java, Bash
- Features: elementcard, its own, retry, secrets, test, timeout
- Source: https://github.com/voxgig-sdk/voxgig-elementdemo-sdk

## Where to start

- Building an SDK for your own API: [create-sdkgen](https://voxgig.com/sdk/docs/create-sdkgen).
- Understanding what the generator can produce: [sdkgen](https://voxgig.com/sdk/docs/sdkgen).
- The SDK's shape is wrong and you need to correct it: [apidef](https://voxgig.com/sdk/docs/apidef).
- Extending the toolchain rather than using it: [docgen](https://voxgig.com/sdk/docs/docgen), which is the worked example of a package.

## Elsewhere on this site

- [SDK features](https://voxgig.com/sdk/features): what the 19 generated features do.
- [Customization](https://voxgig.com/sdk/custom): the levers, up to entirely custom language targets.
- [Generator comparisons](https://voxgig.com/sdk/comparisons): Voxgig against the other generators.
- [SDK Catalog](https://voxgig.com/voxgig-sdk): 600+ generated SDKs, readable without installing anything.