How-to › Ship an SDK

How to score SDK generators on your API with a repeatable rubric#

Record what each SDK generator does with your own OpenAPI document, keep the raw measurements beside per-team weights, and rescore without a generator run.

Audience
Platform team
Level
intermediate
Topic
Choose a generator and generate an SDK
Verified

Your team picked a generator from a demo on the Petstore document.1 Your own API returns tracking events as a oneOf, signs requests with a bearer token, and pages with a cursor. The client you chose types none of the event fields your app renders, and the spreadsheet that chose it holds one total per tool, so nobody can see which column decided.

What you get

You will end up with a rubric that scores generators from recorded evidence, keeps every raw measurement beside the weights, and lets each team reweight without a rerun. This is for you if you are choosing a generator for an API you own.

Short answer

Run each candidate generator twice on your own OpenAPI document and build what it writes. Record the evidence: operations reached, languages built, identical runs, runtime dependencies, license, and probes for the schemas and auth scheme your API uses. Score that evidence with one weights file per team, and make a must-have probe a gate rather than points. On the Depot document here, sdkgen, oapi-codegen and openapi-typescript reached all eight operations and differed on the probes.

You will need

An OpenAPI 3 document for your API, Node 22 or later, and Go. oapi-codegen v2.8.2 needs Go 1.25, and its runtime module v1.9.1 needs Go 1.26; the go command fetches each toolchain itself when GOTOOLCHAIN=auto is in effect. The sample’s document, api.json, describes a parcel API with eight operations, a oneOf with a discriminator, a bearer scheme, and a cursor parameter. Verified 2026-11-21.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-written SDKOne language, a small API, and ergonomics no generator producesEvery column of the rubric becomes a review task, repeated for each language you addA second language, or a document that changes monthly
oapi-codegenGo only, and you want one generated file to reviewGo alone, three runtime modules, and one method per operation for callers to learnYou ship clients in more than one language
openapi-typescript and openapi-fetchTypeScript only, and you want types with a small runtimeA path-keyed call style, and auth left to a middleware you writeCallers want named methods, or you need another language
sdkgenSeveral languages from one model, with entity-shaped clientsA model to read, a large generated tree, and gaps where the model drops schemasOne language, or your API leans on oneOf responses

Voxgig maintains sdkgen. It is one of four approaches on this page, and its row lists its costs.

The two single-language generators are cheaper to review, because each writes one file, and they typed the event and quote fields the probes look for. sdkgen built TypeScript and Go from one model whose manifests declare no runtime package, at the price of 187 generated files and two failed probes.

Write probes from your own document

A probe is a check your document needs and Petstore cannot ask for. Write one per feature your API depends on, as regular expressions that must each match a line of generated code.

{
  "api": [
    { "name": "oneOf variants typed", "patterns": ["\\bfacility\\b", "\\bsignedBy\\b"] },
    { "name": "array response typed", "patterns": ["\\bcarrier\\b", "\\bpriceCents\\b"] },
    { "name": "bearer scheme in code", "patterns": ["['\"`]Bearer['\"`]"] }
  ],
  "petstore": [
    { "name": "x-next paging header typed", "patterns": ["x-next"] }
  ]
}

facility and signedBy are fields of the two variants of TrackingEvent. carrier and priceCents belong to the array that quoteRates returns. probe.mjs removes // and /* */ comments before it matches, because a probe that counts a comment passes for a generator that wrote nothing.

Run every candidate twice and record the evidence

record.sh scaffolds or runs each generator twice into empty directories, builds the first run, and writes evidence/. The sdkgen step:

  for RUN in 1 2; do
    status "$DOC sdkgen run $RUN"
    D="$WORK/$DOC/sdkgen-run$RUN"
    rm -rf "$D" && mkdir -p "$D" && cp "$SRC" "$D/$DOC.json"
    (cd "$D" && npx --yes "$CREATE_SDKGEN" "$NAME" --def "$DOC.json" --target ts --target go > scaffold.log 2>&1)
    (cd "$D/$NAME-sdk/.sdk" && npm run generate > ../../generate.log 2>&1)
  done

Each run’s file hashes go into run1.sha256 and run2.sha256. An operation counts as reached when the output has a handle for its method and path. In sdkgen that is a point in the extracted model, in oapi-codegen a *Client method named after the operationId, and in openapi-typescript a path entry typed with operations[...]. Runtime dependencies are what the generated manifests declare, so code a generator copies into its output does not count. For sdkgen the comparison covers the ts/ and go/ trees. The record files under .sdk/log and .jostraca differed between the two scaffolds, so a comparison of the whole project reports a difference the SDK does not have. The scoring scripts read only evidence/, so a team can reweight offline.

Read the raw measurements before any total

node measure.mjs api
api.json: 8 operations, 3 probes
measured                sdkgen              oapi-codegen        openapi-typescript
version                 4.44.3              v2.8.2              7.13.0
operations reached      8/8                 8/8                 8/8
languages built         2/2 go,typescript   1/1 go              1/1 typescript
two runs identical      yes, 187 files      yes, 1 file         yes, 1 file
names a caller learns   3 entities          8 methods           5 paths
runtime dependencies    0                   3                   2
license                 MIT                 Apache-2.0          MIT
oneOf variants typed    no                  yes                 yes
array response typed    no                  yes                 yes
bearer scheme in code   yes                 no                  no

Coverage ties, and so does repeatability. Every row is recomputed from the committed evidence/, so a team that doubts a cell reruns record.sh and compares. The probes separate the three. sdkgen’s model kept no fields for TrackingEvent and took the rate entity’s fields from the request body, so neither the event fields nor the quote fields reached its code. It reached cancelShipment as a second point of create, selected by an $action key:

  op: {
    create: {
      name: "create"
      points: [
        {
          co: {
            id: "POST /shipments/{shipmentId}/cancel"
            source: "openapi3"
            version: 2
          }

The same run on @voxgig/sdkgen 4.45.0 with @voxgig/apidef 8.33.1, the highest releases on npm that day, renamed tracking_event to event and failed the same two probes. No probe covers pagination. sdkgen’s model records the cursor as body.nextCursor, and the scaffold added no paging feature to either target.

Check unions and auth in oapi-codegen and openapi-fetch

oapi-codegen reads a YAML file passed with -config. Its README says the remaining command-line options should be considered deprecated, so record.sh writes package, output, and generate with models: true and client: true. The oneOf became a union type with AsScanEvent, FromScanEvent, MergeScanEvent and a Discriminator method, which is why it passed the first probe. No auth code was generated for the bearer scheme. A caller adds the header with a RequestEditorFn, or with NewSecurityProviderBearerToken from its securityprovider package.

openapi-typescript writes types only,2 and openapi-fetch makes the calls with client.GET('/shipments'). The union came out as components["schemas"]["ScanEvent"] | components["schemas"]["DeliveryEvent"]. Its auth guide says the library works with any Authorization setup, and sets the header in a middleware’s onRequest, which is code you own. The sample’s callers/api.caller.ts calls all eight operations, and tsc --strict accepted it.

Reweight per team, and gate on the must-haves

Each weights file lists the languages a team needs, the licenses it accepts, its budget, its must-haves, and a weight for every column. The two files here are examples for a team to replace, not a recommendation. The platform team needs TypeScript and Go:

node score.mjs api weights/platform.json
weights/platform.json: platform team shipping TypeScript and Go clients
column (weight)         sdkgen              oapi-codegen        openapi-typescript
coverage (3)            1.00                1.00                1.00
builds (2)              1.00                1.00                1.00
repeatable (2)          1.00                1.00                1.00
shape (1)               0.63                0.00                0.38
runtime (1)             1.00                0.25                0.33
footprint (1)           0.31                1.00                1.00
languages (3)           1.00                0.50                0.50
probes (3)              0.33                0.67                0.67
license (1)             1.00                1.00                1.00
price (1)               1.00                1.00                1.00
total                   82.9                76.4                78.9
rank: sdkgen, openapi-typescript, oapi-codegen

Under these weights sdkgen ranks first, from the languages and runtime columns, and the total hides that it failed the event probe. The web team renders every tracking event, so it makes that probe a must:

node score.mjs api weights/web-team.json | tail -3
total                   out                 73.6                90.7
out: sdkgen fails a must, oneOf variants typed
rank: openapi-typescript, oapi-codegen

Under the web team’s file sdkgen is out, removed by the must before any weight applied, and openapi-typescript ranks first. Publish the raw table beside every total, so a reader can redo the judgement call the weights made.

Check it worked

node --test rubric.test.mjs
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0

The tests fail if an operation drops out of any output, or if a probe counts a comment. They also fail if a recorded probe disagrees with a rerun on the committed sources, or if two differing runs read as identical. score also refuses a weights file that leaves out a column, so a missing weight cannot read as 0.

When it goes wrong

The ranking flips when the document changes. Petstore asks none of the Depot probes, so under the same weights it ranks the three in another order, with sdkgen last:

node score.mjs petstore weights/platform.json | tail -1
rank: openapi-typescript, oapi-codegen, sdkgen

The generators and the weights were the same in both runs, and only the document changed. Score on the document you ship, and write a probe for each oneOf, scheme, and paging rule it declares.

A probe passes on a comment. A generator that mentions Bearer in a doc comment and applies nothing reads as supporting the scheme. Strip comments before matching, as probe.mjs does.

Two runs look different because the comparison included log files. Compare the generated trees, and list what you left out.

When not to do this

Do not build a rubric to choose between two generators when one of them cannot produce your language. The language column decides, and the rest is ceremony.

Do not read sdkgen’s lead under the platform weights as a verdict. It comes from the languages and runtime columns, and a team whose API returns oneOf events should gate on that probe first. oapi-codegen is the better fit for a Go-only service, because it writes one reviewable file and passed both schema probes. openapi-typescript with openapi-fetch suits a TypeScript web app that needs every union typed and can own its auth middleware.

Do not treat a grep probe as proof of behavior. It shows that a name reached the code, so test a must-have with a call against a stand-in server before you sign off.

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, oapi-codegen v2.8.2 with its runtime v1.9.1, openapi-typescript 7.13.0, openapi-fetch 0.17.0 and TypeScript 5.9.3. The generators ran once through record.sh, which wrote the committed evidence/, and again in a copy, which wrote an identical tree. Every output block is what the command preceding it printed from that evidence. The sheet scores only these three generators, because OpenAPI Generator, Kiota, Speakeasy and Fern, which the page’s brief also names, were not run for it.

Footnotes

  1. The Petstore document comes from the OpenAPI Initiative’s example descriptions, whose footer licenses the work under Creative Commons Attribution 4.0 International. The file’s own info.license block names MIT, which the specification defines as the license information for the exposed API. The MIT license therefore covers a pet shop that does not exist, while the file describing it is under CC BY 4.0. ↩︎ Back to text

  2. The openapi-typescript governance file describes it as a 100% volunteer open source project that no legal entity backs financially, and says it accepts sponsorship to maintain it. The price input in inputs.json records what a user pays, which is zero, and is a different number from what the project costs its maintainers. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.