How-to › Ship an SDK

How to add a custom target to a generation run in your own repo#

Add an output the generator does not ship as a target kept in your project, compared with a meta-scaffolded generator and a templating step after generation.

Audience
Library maintainer
Level
advanced
Topic
Customize a generator without forking
Languages
TypeScript
Verified

Read first: Generate a code section with code instead of a template

Your team wants a request file for the API beside the TypeScript SDK, one block per operation, for testing in an editor. sdkgen ships no such target. An upstream pull request waits on a maintainer, and a script that writes the file into ts/src gets packed into the published SDK.

What you get

You will end up with a custom target that lives in your project, regenerates with the rest, and writes into a folder of its own. This is for you if you need one more output and will maintain it.

Short answer

In an sdkgen project, add .sdk/model/target/<name>.aontu and a Main_<name> component under .sdk/src/cmp/<name>/, run voxgig-sdkgen target add <name>, and generate. The target reads the same model as every other target, writes into its own folder, and generate fails on a file name that climbs out of it. With Swagger Codegen or OpenAPI Generator, scaffold a generator class with meta, build it, and put it on the class path.

You will need

Node 22 or later, an sdkgen project you can regenerate, and Java with Maven for the two Java generators. Read the prerequisite on components first: a target’s code is a component. The sample in code/ commits every generator’s output, so its checks run offline on Node alone.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
OpenAPI Generator meta command custom generatorYou already run OpenAPI Generator and can build a Java jarA Java class and Mustache templates to maintain, plus a class path on every runThe output needs entity names rather than operationIds
sdkgen custom targetsAn sdkgen project, and the output should follow its modelYours to maintain, and doctor reports your own target file as forkedYou do not generate with sdkgen
Separate templating stepAny generator, or none, and a small outputRebuilds from the document whatever it needs, and nothing stops it writing anywhereThe output needs the generator’s classification
Swagger Codegen meta command custom generatorYou run Swagger Codegen 3 and its OpenAPI 3.0 reading suits youThe same Java class and template work as OpenAPI Generator, on a smaller generator listYou want the wider generator list of OpenAPI Generator

Voxgig maintains sdkgen. It is one of four options in the table, not the recommendation.

The in-repo sdkgen target reuses the model and the pipeline it already runs, and is yours to maintain. A separate step owes nothing to any generator and must rebuild what it needs from the document. The two meta generators sit between: a Java project that reuses the generator’s parser and names operations by operationId.

Declare the target and write its component

A target is a model file and a component directory under .sdk. This one, http, is a tool rather than an SDK, so it switches off every standard phase and emits its whole output from Main, as the model reference describes for consumer targets.

main: kit: target: http: {
  title: 'HTTP request file'
  ext: http
  comment: line: "#"
  module: name: '$$name$$'

  phase: {
    entity:     { active: false }
    feature:    { active: false }
    readme:     { active: false }
    agentguide: { active: false }
    test:       { active: false }
  }

  deps: {}
}

Main_http walks the entities in the model and writes one request block per operation point, using the HTTP client format JetBrains documents, with in-place variables written @base and {{bookId}}.

  File({ name: model.name + '.' + target.ext }, () => {
    Content(`# ${model.Name} API requests. Generated by the http target, do not edit.\n`)
    Content(`@base = ${base}\n`)
    each(entities, (entity: any) => {
      if (false === entity.active) return
      each(entity.op || {}, (op: any) => {
        each(op.points || [], (point: any) => {
          const path = String(point.o).replace(/\{(\w+)\}/g, '{{$1}}')
          Content(`\n### ${entity.name}.${op.name}\n${point.m} {{base}}${path}\n`)
          if (point.bf && point.bf.length) {
            const body: any = {}
            for (const field of point.bf) body[field] = ''
            Content(`content-type: application/json\n\n${JSON.stringify(body, null, 2)}\n`)
          }
        })
      })
    })
  })

point.m, point.o and point.bf are the method, path and body fields the model step already extracted, so the component parses nothing.

Add it to the run

From .sdk/, register the target and generate:

npx voxgig-sdkgen target add http
npm run generate

target add logs http: defined in this project, so its files stay as they are, then a warning that no test source exists for the target. Every generate warns that one file in .sdk differs from what its source installs, and npx voxgig-sdkgen doctor names it: the target’s own model file, reported FORKED because no copy record exists for it. Generate still exits 0; doctor exits 1, as the last section shows.

The elementdemo SDK is the worked reference at full size. Its .sdk holds a bash target with Main, Entity and Test components, and its generated test runner seeds from the fixtures in .sdk/test/entity/ that the other targets’ basic tests use.

Scaffold the same output with meta

Swagger Codegen and OpenAPI Generator both scaffold a generator project with meta -o <dir> -n http-requests -p com.example.codegen. The scaffold is a Maven project with a class, a test, three Mustache templates, and a service registration. Writing .http files took three edits to the class, shown in class.diff, and one api.mustache:

# {{appName}} API requests. Generated by the http-requests generator, do not edit.
@base = {{{basePath}}}
{{#operations}}
{{#operation}}

### {{operationId}}
{{httpMethod}} {{=<% %>=}}{{base}}<%={{ }}=%>{{{path}}}
{{#hasBodyParam}}
content-type: application/json

{}
{{/hasBodyParam}}
{{/operation}}
{{/operations}}

Build with mvn package, then run the CLI with the jar on its class path: org.openapitools.codegen.OpenAPIGenerator generate -g http-requests for OpenAPI Generator, and io.swagger.codegen.v3.cli.SwaggerCodegen generate -l http-requests for Swagger Codegen. Both wrote DefaultApi.http under a Java-package path, src/org/openapitools/api/ and src/io/swagger/client/api/.1

For this particular file, OpenAPI Generator needs no class at all. It bundles a jetbrains-http-client generator, marked experimental, and generate -g jetbrains-http-client wrote Apis/DefaultApi.http with every path variable already written {{bookId}}. It names each request from the operation’s summary, which the Bookshelf document leaves out, so all five headings came out blank. Swagger Codegen 3.0.85 lists no such generator, so its route is meta.

bolt-on.mjs is the separate step: it reads api.json, walks paths, and prints the same blocks. compare.mjs reads all four outputs.

node compare.mjs
operation               sdkgen            openapi-generator swagger-codegen   bolt-on
GET /books              book.list         listBooks         listBooks         listBooks
POST /books             book.create       createBook        createBook        createBook
GET /books/{bookId}     book.load         getBook           getBook           getBook
PATCH /books/{bookId}   book.update       updateBook        updateBook        updateBook
DELETE /books/{bookId}  book.remove       deleteBook        deleteBook        deleteBook
sdkgen             writes the path as /books/{{bookId}}
openapi-generator  writes the path as /books/{bookId}
swagger-codegen    writes the path as /books/{bookId}
bolt-on            writes the path as /books/{{bookId}}

The two meta generators name requests by operationId, and the template prints the path as the document writes it. A REST client reads only {{bookId}} as a variable, so the fix is Java in the generator class. OpenAPI Generator’s scaffold already overrides postProcessOperationsWithModels for such changes; Swagger Codegen’s leaves the method to add.

Check it worked

generate.sh ran npm run generate twice and fingerprinted every output file each time. The tests compare the fingerprints and check that each output carries all five operations.

node --test target.test.mjs
# tests 9
# suites 0
# pass 9
# fail 0

The fourth test asserts the only .http file in the tree is ./http/bookshelf.http, so a target that strays into another folder fails it.

When it goes wrong

A target that writes into another target’s folder is the failure to guard against. Generate failed on both ways of aiming http at ts/ that the sample tried. The file writer refuses any name with a .. segment. output.path, which exists to send a target to another repository, refuses any path inside the SDK project, the target’s own folder included. A separate step has no such check.

node pitfall.mjs
Main_http writes File({ name: '../ts/bookshelf.http' })
  generate exit 1: File name must not contain a ".." path segment, name=../ts/bookshelf.http
project.aontu sets main: kit: target: http: output: path: 'ts'
  generate exit 1: External output path is inside the SDK project.
a separate step writes ts/src/bookshelf.http, then generate runs
  ts/src/bookshelf.http after generate: present
  in the npm pack file list: true
npx voxgig-sdkgen doctor, with the http target added
  FORKED (no copy record, so an add stops on it; --force takes the source copy): model/target/http.aontu
  .sdk has drifted: 1 forked, 0 edited, 0 stale, 0 missing, 0 outdated, 0 unresolved
  doctor exit 1

The stray file survives regeneration, and the files list in the TypeScript package.json includes src, so npm pack ships it. Give the separate step a folder no generator owns.

The second failure is a CI job that runs doctor as a gate. It goes red as soon as the project has a target of its own, because doctor counts the target’s model file as forked and exits 1. Allow that one finding by path rather than dropping the gate.

When not to do this

Do not build an sdkgen target for an output that reads the document alone. bolt-on.mjs writes the requests by operationId in under thirty lines and owes nothing to any generator.

Skip sdkgen when your SDKs come from Swagger Codegen or OpenAPI Generator. For this request file, OpenAPI Generator’s bundled jetbrains-http-client generator is the better choice, because it needs no code of yours. A meta generator reuses the parser you already trust, and Swagger Codegen is the better choice when you already run it on OpenAPI 3.0 documents. OpenAPI Generator suits a team that wants its wider generator list, or 3.1 documents, which its README marks as beta support.

Do not expect the in-repo target to be free: sdkgen upgrades can change the model shape your component reads.

Last verified

Verified 2026-11-20 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, OpenAPI Generator 7.27.0, and Swagger Codegen 3.0.85 on OpenJDK 21.0.13 and Maven 3.9.11. Every output block is what the command preceding it printed. The generators ran once, recorded in generate.sh, OpenAPI Generator’s bundled jetbrains-http-client included; the lines pitfall.mjs prints are what that run logged.

Footnotes

  1. OpenAPI Generator’s README says it is a fork of Swagger Codegen. More than 40 top contributors and template creators made it, citing the issues with the Swagger Codegen 3.0.0 beta release and a disagreement over the project’s direction. The two meta scaffolds took the same three edits to their classes, and the one api.mustache on this page rendered byte-identical files in both. ↩︎ 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.