NikolaRusakov/typed-openapi

Generate a headless Typescript API client from an OpenAPI spec

typed-openapi

Generate a Typescript API client from an OpenAPI spec

See the online playground

Features

• Headless API client, bring your own fetcher ! (fetch, axios, ky, etc...)
• Generates a fully typesafe API client with just types by default (instant suggestions)
• Or you can also generate a client with runtime validation using one of the following runtimes:
  • zod
  • typebox
  • arktype
  • valibot
  • io-ts
  • yup

The generated client is a single file that can be used in the browser or in node. Runtime validation schemas are provided by the excellent typebox-codegen

Install & usage

pnpm add typed-openapi

It exports a bunch of functions that can be used to build your own tooling on top of it. You can look at the CLI code so see how to use them.

CLI

npx typed-openapi -h

typed-openapi/0.1.3

Usage: $ typed-openapi <input>

Commands: <input> Generate

For more info, run any command with the `--help` flag: $ typed-openapi --help

Options: -o, --output <path> Output path for the api client ts file (defaults to `<input>.<runtime>.ts`) -r, --runtime
<name> Runtime to use for validation; defaults to `none`; available: 'none' | 'arktype' | 'io-ts' | 'typebox' |
'valibot' | 'yup' | 'zod' (default: none) -h, --help Display this message -v, --version Display version number

Non-goals

• Caring too much about the runtime validation code. If that works (thanks to typebox-codegen), that's great, otherwise I'm not really interested in fixing it. If you are, feel free to open a PR.

• Supporting all the OpenAPI spec. Regex, dates, files, whatever, that's not the point here. openapi-zod-client does a great job at that, but it's slow to generate the client and the suggestions in the IDE are not instant. I'm only interested in supporting the subset of the spec that makes the API client typesafe and fast to provide suggetions in the IDE.

• Splitting the generated client into multiple files. Nope. Been there, done that. Let's keep it simple.

Basically, let's focus on having a fast and typesafe API client generation instead.

Alternatives

openapi-zod-client, which generates a zodios client but can be slow to provide IDE suggestions when the OpenAPI spec is large. Also, you might not always want to use zod or even runtime validation, hence this project.

Contributing

• pnpm i
• pnpm build
• pnpm test

When you're done with your changes, please run pnpm changeset in the root of the repo and follow the instructions described here.