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

Source: https://voxgig.com/howto/generate-a-readme-from-an-api-description

- Audience: api-producer
- Level: advanced
- Languages: typescript
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](https://mustache.github.io/mustache.5.html) | 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](https://learn.microsoft.com/en-us/openapi/kiota/using) | 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](https://github.com/RicoSuter/NSwag/wiki/CommandLine) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | 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](https://github.com/Mermade/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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) 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:

```aontu title="sdkgen/text.aontu"
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.

```aontu title="sdkgen/project.aontu"
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`:

```bash
cat records/sdkgen-4.44.3.txt
```

```text output
@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`](https://learn.microsoft.com/en-us/openapi/kiota/using) 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:

```js title="render.mjs"
/** 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:

```bash
node demo.mjs
```

```text output
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:

```bash
node typecheck.mjs
```

```text output
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:

```bash
node --test readme.test.mjs | tail -8
```

```text output
# 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](https://mustache.github.io/mustache.5.html) 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

- [Add a docs output to an existing generated SDK project](/howto/add-a-docs-output-to-a-generated-sdk)

- [Keep code samples for six SDK languages in sync](/howto/keep-sdk-code-samples-in-sync)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Detect a reference site drifting from its OpenAPI spec](/howto/check-a-reference-site-in-ci)

- [Release reference docs and the SDK from one tag](/howto/release-reference-docs-with-the-sdk)

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

[^1]: The [Mustache manual](https://mustache.github.io/mustache.5.html) 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.

[^2]: The [widdershins README](https://github.com/Mermade/widdershins) 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.