How-to › Document and support developers

How to generate a package README from your API description#

Generate the package README from the OpenAPI document, keep hand-written prose where regeneration cannot reach it, and prove a second run changes nothing.

Audience
API producer
Level
advanced
Topic
Ship docs with the code
Languages
TypeScript
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-written Mustache template with markersYour generator writes no README, and you want the opening written by peopleA template, a renderer and the marker rules to maintain, plus escaping meant for HTMLThe generator already writes the README you need
KiotaClients in several languages from one tool, with kiota info listing the runtime packagesIt writes no README, so the install line and the calls come from your own templateYou want the README to arrive with the client
NSwagA TypeScript or C# client named after operationIds, and a .NET toolchain at handNo command writes documentation, so every README line is yours to generateYour build has no .NET runtime
sdkgen README per targetAn sdkgen client, where the README should list the same entities the model doesThe whole file is rewritten each run, so prose belongs in text.aontu slotsYour opening runs longer than the slots allow
widdershinsA long Markdown reference for a Slate-style docs site, with HTTP samples per languageA reference of raw HTTP calls, not an install line, and a project with no release since 2020Readers 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 &#x2F;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.

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

  1. 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

  2. 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

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.