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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| OpenAPI Generator meta command custom generator | You already run OpenAPI Generator and can build a Java jar | A Java class and Mustache templates to maintain, plus a class path on every run | The output needs entity names rather than operationIds |
| sdkgen custom targets | An sdkgen project, and the output should follow its model | Yours to maintain, and doctor reports your own target file as forked | You do not generate with sdkgen |
| Separate templating step | Any generator, or none, and a small output | Rebuilds from the document whatever it needs, and nothing stops it writing anywhere | The output needs the generator’s classification |
| Swagger Codegen meta command custom generator | You run Swagger Codegen 3 and its OpenAPI 3.0 reading suits you | The same Java class and template work as OpenAPI Generator, on a smaller generator list | You 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.
Related how-tos
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
-
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
metascaffolds took the same three edits to their classes, and the oneapi.mustacheon this page rendered byte-identical files in both. ↩︎ Back to text