Client Generators

Writing custom client generators

A generator is a plain module: (input) => GeneratedFile[]. It receives the language-agnostic API model and returns files — in ANY output language. It runs in the same pass as the built-ins; select it by path in redocly.yaml:

client:
  generators: [typescript, ./generators/my-generator.mjs]

The contract

/** @type {import('@redocly/client-generator').CustomGenerator} */
export default {
  name: 'my-generator',
  run({ model, output, outputMode, emit }) {
    return [{ path: output.path.replace(/\.ts$/, '.mine.txt'), content: '…' }];
  },
  // Optional: one idiomatic call snippet per operation for docs (x-codeSamples),
  // collected into an overlay file when `client.codeSamples: true` is set.
  sample(operation, { model, emit }) {
    return { lang: 'python', source: '…' };
  },
  // Optional: the reference page for what `run` emits, written when `client.docs` (or
  // --docs) is on. Same `{ path, content }` shape as `run`; `renderReferencePage` gives
  // the standard layout and takes `sample` for its snippets. A generator documents itself.
  docs({ model, output, emit }) {
    return [{ path: output.path.replace(/\.ts$/, '.mine.md'), content: '…' }];
  },
};

Declaring options

A generator that needs configuration declares it as a schema; run then receives options already validated, with defaults applied:

export default {
  name: 'permissions-matrix',
  options: {
    type: 'object',
    properties: { groupBy: { enum: ['tag', 'path'], default: 'tag' } },
    additionalProperties: false,
  },
  run({ model, output, options }) {
    return [
      { path: output.path.replace(/\.ts$/, '.permissions.md'), content: render(options.groupBy) },
    ];
  },
};

Users set them per generator name:

client:
  generators: [typescript, ./generators/permissions-matrix.mjs]
  options:
    permissions-matrix:
      groupBy: path

The supported subset is a top-level type: 'object' with properties, required, and additionalProperties; each property is a scalar (string/number/boolean), an enum, or an array of scalars, and may carry a default and a description. Don't validate options inside run — an unknown key, a wrong type, a value outside an enum, or a missing required key already fails generation before run is called.

Rules: output is deterministic (same description → same bytes); never add dependencies to the generated client; never hand-edit generated output — edit this generator and regenerate. Emitted file paths must stay inside the --output directory (subdirectories are fine) — escapes are rejected. Optionally declare requiresGenerator — the @redocly/client-generator version range you wrote this against ('^1.2.0', '~1.2.0', '>=1.2.0', or an exact version). A CLI outside the range then fails with the fix path instead of feeding your generator an unexpected model shape. Ejected generators carry it automatically; hand-written ones without it are taken as current.

The model (IR)

model.services[].operations[] — each operation carries name, specName, method, path, tags, pathParams/queryParams/headerParams/cookieParams, requestBody, successResponses/errorResponses (each with a schema), and security. model.schemas holds the named schemas. Every schema is a discriminated union on kind: scalar, array, object, record, ref, literal, enum, union (optionally with a discriminator), intersection (allOf), null, unknown, omit.

Helpers (import from '@redocly/client-generator')

Worked example: the built-in python generator (packages/client-generator/src/generators/python/index.ts in the Redocly CLI repo) is authored with exactly this toolkit and nothing else — models via flattenAllOf/ enumValues/discriminatorCases, all code through Printer, every name through identifierFor(..., RESERVED_WORDS.python).

A generator that emits TypeScript may additionally use the source-text renderers from @redocly/client-generator/generate — tsType (schema → type), tsJsdoc, codeLiteral, operationSignature, pascalCase, safeIdent. There is no AST toolkit and no typescript dependency: every generator prints text through Printer.

The loop

1. Edit the generator.
2. Run redocly generate-client.
3. Inspect git diff of the generated output.
4. Repeat. Generated files are never hand-edited.

If you had to work around a missing helper or a wrong default, tell the user and suggest filing an issue at https://github.com/Redocly/redocly-cli/issues — include the generator snippet and the helper you expected to exist.