Quick Start

Install the latest NodeJS LTS release, though any recent version of NodeJS will likely work.

You’ll also need either an OpenAPI v3 / v3.1, or TypeSpec API specification to generate from. You can provide OpenAPI specifications as YAML or JSON, local files or remote urls - we’ll load them all! 🚀

Cross-file references are also supported, so don’t worry about pre-processing the input.

You can check the version we develop and test against here.

Install dependencies

First install the CLI and the required runtime packages to your project:

npm i --dev @nahkies/openapi-code-generator
npm i @nahkies/typescript-fetch-runtime

pnpm add --dev @nahkies/openapi-code-generator
pnpm add @nahkies/typescript-fetch-runtime

yarn add --dev @nahkies/openapi-code-generator
yarn add @nahkies/typescript-fetch-runtime

bun add --dev @nahkies/openapi-code-generator
bun add @nahkies/typescript-fetch-runtime

You could also install the CLI globally if you prefer, but it’s best to version it per project.

Run generation

This will generate the client to ./src/generated/clients/some-service

You can provide either a local file path or url for the input file.

npm run openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated/clients/some-service \
--template typescript-fetch

pnpm run openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated/clients/some-service \
--template typescript-fetch

yarn openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated/clients/some-service \
--template typescript-fetch

bun run openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated/clients/some-service \
--template typescript-fetch

Profit

Use your new type-safe client, and never worry about making a typo in a url or parameter name again. Let the typescript compiler take care of checking that for you.

See Guide to typescript-fetch client template for more details.

Install dependencies

First install the CLI and the required runtime packages to your project:

npm i --dev @nahkies/openapi-code-generator
npm i axios @nahkies/typescript-axios-runtime

pnpm add --dev @nahkies/openapi-code-generator
pnpm add axios @nahkies/typescript-axios-runtime

yarn add --dev @nahkies/openapi-code-generator
yarn add axios @nahkies/typescript-axios-runtime

bun add --dev @nahkies/openapi-code-generator
bun add axios @nahkies/typescript-axios-runtime

You could also install the CLI globally if you prefer, but it’s best to version it per project.

Run generation

This will generate the client to ./src/generated/clients/some-service

You can provide either a local file path or url for the input file.

npm run openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated/clients/some-service \
--template typescript-axios

pnpm run openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated/clients/some-service \
--template typescript-axios

yarn openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated/clients/some-service \
--template typescript-axios

bun run openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated/clients/some-service \
--template typescript-axios

Profit

Use your new type-safe client, and never worry about making a typo in a url or parameter name again. Let the typescript compiler take care of checking that for you.

See Guide to typescript-axios client template for more details.

Install dependencies

First install the CLI and the required runtime packages to your project:

npm i --dev @nahkies/openapi-code-generator @types/koa @types/koa__router
npm i @nahkies/typescript-koa-runtime @koa/cors @koa/router koa koa-body zod

pnpm add --dev @nahkies/openapi-code-generator @types/koa @types/koa__router
pnpm add @nahkies/typescript-koa-runtime @koa/cors @koa/router koa koa-body zod

yarn add --dev @nahkies/openapi-code-generator @types/koa @types/koa__router
yarn add @nahkies/typescript-koa-runtime @koa/cors @koa/router koa koa-body zod

bun add --dev @nahkies/openapi-code-generator @types/koa @types/koa__router
bun add @nahkies/typescript-koa-runtime @koa/cors @koa/router koa koa-body zod

You could also install the CLI globally if you prefer, but it’s best to version it per project.

You can provide either a local file path or url for the input file.

Run generation

This will generate the server router and validation logic to ./src/generated

npm run openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated \
--template typescript-koa

pnpm run openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated \
--template typescript-koa

yarn openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated \
--template typescript-koa

bun run openapi-code-generator \
--input ./openapi.yaml \ # or https://example.com/openapi.{json,yaml}
--output ./src/generated \
--template typescript-koa

Profit

Implement handlers for your server, and be confident that they match what the client expects. Everything will be strongly typed, so typos are surfaced at development time, not runtime.

By default the runtime validation is using zod.

See Guide to typescript-koa client template for more details.

CLI options

See the cli reference for the full range of supported options, or try

npm run openapi-code-generator --help

pnpm run openapi-code-generator --help

yarn openapi-code-generator --help

bun run openapi-code-generator --help

Typespec specifications

If you want to use typespec instead of openapi3 as your input specifications, additionally install the typespec compiler and supporting packages.

npm i --dev @typespec/compiler @typespec/http @typespec/openapi @typespec/openapi3 @typespec/versioning

pnpm add --dev @typespec/compiler @typespec/http @typespec/openapi @typespec/openapi3 @typespec/versioning

yarn add --dev @typespec/compiler @typespec/http @typespec/openapi @typespec/openapi3 @typespec/versioning

bun add --dev @typespec/compiler @typespec/http @typespec/openapi @typespec/openapi3 @typespec/versioning

Depending on how your typespec specification is written, you may need to install additional packages such as @typespec/rest.

You can then generate like so:

npm run openapi-code-generator \
  --input ./some-service.tsp \ # or https://example.com/some-service.tsp
  --input-type=typespec \
  --output ./src/generated/clients/some-service \
  --template typescript-fetch

pnpm run openapi-code-generator \
  --input ./some-service.tsp \ # or https://example.com/some-service.tsp
  --input-type=typespec \
  --output ./src/generated/clients/some-service \
  --template typescript-fetch

yarn openapi-code-generator \
  --input ./some-service.tsp \ # or https://example.com/some-service.tsp
  --input-type=typespec \
  --output ./src/generated/clients/some-service \
  --template typescript-fetch

bun run openapi-code-generator \
  --input ./some-service.tsp \ # or https://example.com/some-service.tsp
  --input-type=typespec \
  --output ./src/generated/clients/some-service \
  --template typescript-fetch

You can see examples of code generated from typespec specifications here

Roadmap Tips for Writing Specifications

Quick Start

Fetch Client

Axios Client

Koa Server

Install dependencies

Run generation

Profit

Install dependencies

Run generation

Profit

Install dependencies

Run generation

Profit

CLI options

Typespec specifications