A support engineer adds a paragraph about billing to the package README, and the next release ships without it, because the generator rewrote the whole file. The README on the other packages is typed by hand, so its install line names last year’s package and its first example calls a method the client renamed.
What you get
You will end up with a package README generated from the OpenAPI document, prose kept where a regeneration cannot delete it, and a record that a second run changes nothing. This is for you if you publish a generated client.
Short answer
sdkgen writes a README per package on every generate, with the install line, the entities, and a
first call taken from the model, so put your wording in .sdk/model/text.aontu. Kiota and NSwag
write no README, so fill a Mustache template from the document and replace only the text between
generated markers. In both cases regenerate twice and confirm nothing changed, and keep prose
outside the generated parts.
You will need
Node 22 or later and an OpenAPI 3 document. Verified 2026-11-21 against Node 22.23.5,
@voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, Kiota 1.39.0, NSwag 14.8.0,
mustache 4.2.0 and widdershins 4.0.1. The sample’s api.json is a Bookshelf API with five
operations, and api-v2.json adds two operations on /authors to stand for a spec change.
This release has no docs add action: the CLI answers Unknown action: docs, as the record
below shows. A scaffold writes a README.md for each target and one for the repository, and the
separate docs outputs are called editions.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hand-written Mustache template with markers | Your generator writes no README, and you want the opening written by people | A template, a renderer and the marker rules to maintain, plus escaping meant for HTML | The generator already writes the README you need |
| Kiota | Clients in several languages from one tool, with kiota info listing the runtime packages | It writes no README, so the install line and the calls come from your own template | You want the README to arrive with the client |
| NSwag | A TypeScript or C# client named after operationIds, and a .NET toolchain at hand | No command writes documentation, so every README line is yours to generate | Your build has no .NET runtime |
| sdkgen README per target | An sdkgen client, where the README should list the same entities the model does | The whole file is rewritten each run, so prose belongs in text.aontu slots | Your opening runs longer than the slots allow |
| widdershins | A long Markdown reference for a Slate-style docs site, with HTTP samples per language | A reference of raw HTTP calls, not an install line, and a project with no release since 2020 | Readers install a package and copy its calls |
A README the generator writes in full never names a method the client lacks, and it reads like a catalogue, because every sentence comes from the model. The template with markers keeps a human opening at the price of a second program. widdershins writes a reference rather than a package README, deterministically.
Voxgig maintains sdkgen; this page treats it as one row of five.
Put the wording in the model, not the README
sdkgen’s README text has slots in the model, and the
model reference says text
edited into README.md is lost on the next generate. The scaffold writes .sdk/model/text.aontu
once and keeps it. The sample appends a tagline and an entity description to it:
main: kit: text: {
tagline: 'Read and shelve books from TypeScript.'
entity_desc: { book: 'A book on the shelf, with its author and year.' }
}
The install line comes from the target’s publishing settings in .sdk/model/project.aontu. A
package marked active gets an npm install line with its name.
main: kit: target: ts: publish: registry: { state: 'active', package: '@example/bookshelf' }
Regenerate twice, edit by hand, change the spec
record.sh scaffolded the project, generated, generated again, added a paragraph to both
READMEs, generated, and then generated from api-v2.json:
cat records/sdkgen-4.44.3.txt
@voxgig/sdkgen 4.44.3
@voxgig/apidef 8.32.4
voxgig-sdkgen docs add: exit 1, Unknown action: docs (expected: doctor, edition, feature, package, target)
generate, with the wording in text.aontu and the package in project.aontu
ts/README.md install line: npm install @example/bookshelf
ts/README.md second line: Read and shelve books from TypeScript.
README.md entity rows: 1
| **Book** | A book on the shelf, with its author and year. | `/books` |
ts/README.md entity sections: Book
generate again, nothing changed
files compared: 808, changed: 2
.jostraca/jostraca.meta.log (matched by jostraca.meta.log in the project .gitignore)
.sdk/model/.jostraca/jostraca.meta.log (matched by jostraca.meta.log in the project .gitignore)
changed files .gitignore keeps: 0
a paragraph added by hand to both READMEs, then generate
README.md: hand-added paragraph gone
ts/README.md: hand-added paragraph gone
generate from api-v2.json, which adds /authors
ts/README.md install line: npm install @example/bookshelf
ts/README.md second line: Read and shelve books from TypeScript.
README.md entity rows: 2
| **Author** | The Author entity (list, load). | `/authors` |
| **Book** | A book on the shelf, with its author and year. | `/books` |
ts/README.md entity sections: Author, Book
The second generate changed two log files, both ignored by the project’s own .gitignore, so
git diff after it is empty. The hand-added paragraph went from both files on the next run. The
spec change reached both READMEs with no edit, and the description in text.aontu survived it.
@voxgig/sdkgen 4.45.0, installed into the same project, printed the same lines for every step.
Fill a README for Kiota and NSwag
Neither writes one, as far as their own help shows. Kiota 1.39.0 wrote five TypeScript files,
none of them documentation, and no option kiota generate --help lists mentions docs. nswag help
lists nine commands, none for documentation, and none of the 61 arguments of openapi2tsclient
names a README or docs. Both name their calls predictably, so a template can write them. In the clients they wrote from api.json, NSwag named each method after its
operationId and took a body as an instance of its Book class. Kiota chained a property per path
segment and a byBookId() indexer for the parameter.
kiota info prints the runtime packages
with versions, which the install line reads from generated/kiota/info.json and writes as caret
ranges.
render.mjs fills readme.mustache from the document and replaces only the blocks between
BEGIN GENERATED and END GENERATED markers:
/** Replace each generated block of `current` with the block of the same name in `fresh`. */
export function merge(current, fresh) {
const blocks = new Map([...fresh.matchAll(BLOCK)].map((m) => [m[1], m[0]]))
const begins = [...current.matchAll(/<!-- BEGIN GENERATED: ([a-z-]+) -->/g)].map((m) => m[1])
const whole = [...current.matchAll(BLOCK)].map((m) => m[1])
for (const name of blocks.keys()) {
if (!begins.includes(name)) throw new Error(`README.md has no BEGIN marker for "${name}"`)
if (!whole.includes(name)) throw new Error(`README.md has no END marker for "${name}"`)
}
for (const name of begins) {
if (!blocks.has(name)) throw new Error(`README.md has a block "${name}" the template does not write`)
}
return current.replace(BLOCK, (_, name) => blocks.get(name))
}
The demo runs it on a README for the NSwag client:
node demo.mjs
1. first run, api.json: written; groups: books
2. paragraph added under the title
3. run again, api.json: unchanged; paragraph kept
4. run on api-v2.json: updated; paragraph kept; groups: authors, books
5. the paragraph moved into the operations block, run again: updated; paragraph gone
6. END marker deleted, run again: refused, README.md has no END marker for "install"
The marker is the contract. Prose outside it survives a spec change, and prose inside it goes, as in sdkgen. A README whose marker was deleted is refused rather than rewritten.
Check it worked
Compile the code each template README gives its reader, against the client it names:
node typecheck.mjs
nswag README: first call and 5 table calls, 0 type errors
kiota README: first call and 5 table calls, 0 type errors
Then run the tests:
node --test readme.test.mjs | tail -8
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 2511.944742
Two tests carry the claim. One compiles each template README’s first call and table calls with
TypeScript against the client it names, and expects errors for a wrong indexer, a missing import,
and a README from api-v2.json. The other reads both sdkgen records and expects a lost
paragraph, no kept file changed by a rerun, and the Author row.
When it goes wrong
The README shows /books where the path should be. Mustache escapes every {{variable}} for
HTML, as its manual says, and a README is Markdown.
Pass your own escape function, as render.mjs does, or use triple braces.1
A support paragraph disappears after a release. In sdkgen, it was typed into README.md; move it
into a text.aontu slot such as about_md. With the template, it sat between two markers; move it
before the first one.
A rerun shows changes in git diff. The run read something that varies, a clock, a path, or an
unsorted map. The sdkgen rerun changed only its *.log files, and the template renderer sorts the
paths it reads.
When not to do this
Do not generate the whole README when its first screen sells the package. A generated file lists entities well and introduces them badly, so write the opening by hand and generate the install, first-call and reference parts.
Do not choose widdershins for a package README. It writes a long reference of raw HTTP requests in eight languages, with no install line, and it suits a Slate-style docs site better than any row here.2
Do not adopt sdkgen to get a README. If Kiota or NSwag already generates your client, a template
of a page or two does the job, and NSwag’s methods carry the operationId names, so its calls need
no path walking. Kiota is the better pick when kiota info should drive the install line in
every language you ship.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3
and 4.45.0, @voxgig/apidef 8.32.4, Kiota 1.39.0, NSwag 14.8.0 on the ASP.NET Core runtime
10.0.15, mustache 4.2.0, widdershins 4.0.1 and TypeScript 5.8.3. sdkgen, Kiota, NSwag and
widdershins ran once, in generate.sh and record.sh, with Kiota’s telemetry off, and their
output is committed. On 2026-11-22 widdershins’ last npm release was 4.0.1, published 2020-03-30,
the last commit on its default branch, main, was dated 2022-08-26, and GitHub showed no archive
notice.
Footnotes
-
The Mustache manual calls the language logic-less, because there are no if statements, else clauses, or for loops, only tags. The same page makes HTML escaping the default for every variable, and offers the triple mustache for a value that should arrive as it is. ↩︎ Back to text
-
The widdershins README defines the word as an adverb with three senses. The first two are in a direction contrary to the sun’s course and anticlockwise. The third is helping you produce static documentation from an OpenAPI 3.0, Swagger 2.0 or AsyncAPI 1.x definition, among others. ↩︎ Back to text