Registry / http-networking / openapi-typescript

openapi-typescript

library7.13.0jsnpmunverified

openapi-typescript is a powerful command-line tool and library designed to convert OpenAPI 3.0 and 3.1 specifications into TypeScript type definitions. It produces runtime-free, statically-analyzable types, enabling robust type safety for API clients, facilitating validation of mock data, and streamlining the development of business logic directly from your API's schema. The current stable version is 7.13.0, and the project maintains a healthy and active release cadence, frequently publishing minor or patch versions across its ecosystem of packages (e.g., openapi-typescript, openapi-fetch). A key differentiator is its speed and its minimal dependency footprint, requiring only Node.js and avoiding external runtimes like Java, making it a lightweight and efficient alternative to many traditional OpenAPI codegen solutions. It supports loading schemas from local YAML or JSON files, as well as remote URLs.

http-networking serialization devops

npm install openapi-typescript

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENAPI-TYPESCRIPT

openapi-typescript

http-networkingjavascriptv7.13.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

openapiTS

✓ import openapiTS from 'openapi-typescript';

✗ import { openapiTS } from 'openapi-typescript';

This is for programmatic usage of the generator. The primary CLI usage does not involve this import.

paths

✓ import type { paths } from './my-openapi-3-schema';

✗ import { paths } from './my-openapi-3-schema';

Imported from the *generated* TypeScript definition file, typically with `type` keyword for compile-time usage only. The path depends on your output file.

components

✓ import type { components } from './my-openapi-3-schema';

✗ import { components } from './my-openapi-3-schema';

Imported from the *generated* TypeScript definition file, typically with `type` keyword for compile-time usage only. Provides access to schema definitions. The path depends on your output file.

This quickstart demonstrates how to generate TypeScript types from an OpenAPI schema using the `openapi-typescript` CLI and then how to import and use the generated `paths` and `components` types in a TypeScript application to ensure type safety for API interactions. It fetches a remote Swagger Petstore schema for demonstration.

import { createClient } from '@hey-api/openapi-ts'; // For programmatic usage import { writeFile } from 'node:fs/promises'; import type { paths, components } from './generated-api-types'; // Example usage of generated types async function generateAndUseTypes() { // 1. Generate types using the CLI (most common) console.log('Generating types via CLI...'); try { const { execa } = await import('execa'); await execa('npx', [ 'openapi-typescript', 'https://petstore.swagger.io/v2/swagger.json', // Or a local file: './path/to/my/schema.yaml' '-o', './generated-api-types.d.ts', ], { stdio: 'inherit' }); console.log('Types generated successfully to generated-api-types.d.ts'); // 2. Or, programmatically (uncomment to use) // const petstoreSchema = await (await fetch('https://petstore.swagger.io/v2/swagger.json')).json(); // const types = await openapiTS(petstoreSchema); // await writeFile('./generated-api-types.d.ts', types); // console.log('Types generated programmatically to generated-api-types.d.ts'); // 3. Example usage of generated types in your application type Pet = components['schemas']['Pet']; type CreatePetRequest = paths['/pet']['post']['requestBody']['content']['application/json']; type GetPetByIdResponse = paths['/pet/{petId}']['get']['responses']['200']['schema']; const myPet: Pet = { id: 1, name: 'Buddy', status: 'available', category: { id: 101, name: 'Dogs' }, photoUrls: ['http://example.com/buddy.jpg'] }; console.log('Example Pet type:', myPet); const newPetRequest: CreatePetRequest = { name: 'Fluffy', photoUrls: ['http://example.com/fluffy.png'], tags: [{ id: 1, name: 'cute' }] }; console.log('Example CreatePetRequest type:', newPetRequest); } catch (error) { console.error('Error during type generation or usage:', error); process.exit(1); } } generateAndUseTypes();

openapi-typescript --version

Debug

Known issues

breakingOpenAPI 2.x (Swagger) specifications are no longer supported by `openapi-typescript` starting from version 6.x. Users with older schemas must use `openapi-typescript` v5.x or earlier.

fix

Upgrade your OpenAPI schema to 3.0 or 3.1, or downgrade `openapi-typescript` to a 5.x version if OpenAPI 2.x support is essential.

affects: >=6.0.0

breakingVersion 7.x introduced several breaking changes, including the handling of remote schema fetching via Redocly CLI (requiring `redocly.config.yml` for auth), changes to the Node.js API input types (requiring URLs for file paths), and `defaultNonNullable: true` by default. Globbing for multiple schemas was also replaced by Redocly configuration.

fix

Consult the migration guide for 7.x on the official documentation site. Update your build scripts, programmatic API calls, and potentially introduce a `redocly.config.yml` file.

affects: >=7.0.0

gotchaFor optimal type safety and to prevent common runtime errors with indexed access, it is highly recommended to enable `noUncheckedIndexedAccess: true` in your `tsconfig.json`. Without it, TypeScript may allow accessing arbitrary keys on objects without checking for existence, leading to `undefined` runtime errors.

fix

Add `"noUncheckedIndexedAccess": true` to your `compilerOptions` in `tsconfig.json`.

affects: >=6.0.0

gotchaTo correctly resolve generated type modules, your `tsconfig.json` should have `"module": "ESNext"` (or `"NodeNext"`) and `"moduleResolution": "Bundler"` (or `"NodeNext"`) under `compilerOptions`. Incorrect settings can lead to TypeScript failing to find the generated types.

fix

Update your `compilerOptions` in `tsconfig.json` to include `"module": "ESNext"` and `"moduleResolution": "Bundler"`.

affects: >=6.0.0

gotchaThe `--read-write-markers` flag (introduced in 7.13.0) will wrap `readOnly` properties with `$Read<T>` and `writeOnly` properties with `$Write<T>`. If you use `openapi-fetch`, it leverages `Readable<T>` and `Writable<T>` helpers to exclude these properties. Be aware that enabling this flag changes the generated type structure for such properties.

fix

If using this flag, ensure your consuming code and any associated client libraries (like `openapi-fetch`) are compatible with these type markers. Adjust your code to use the `Readable<T>` or `Writable<T>` helpers if you need to filter these properties.

affects: >=7.13.0

Errors

Common errors & fixes

Cannot find module './my-openapi-3-schema' or its corresponding type declarations.

The TypeScript compiler cannot locate the generated type definition file, often due to an incorrect import path, missing `tsconfig.json` configuration, or the file not being generated.

fix

Ensure the output file path in your `npx openapi-typescript` command matches the import path in your TypeScript files. Verify your `tsconfig.json` includes the directory of the generated file and has correct `moduleResolution` settings (e.g., `"moduleResolution": "Bundler"`). Run the generation command before TypeScript compilation.

Property 'someProperty' is possibly 'undefined'.

This common TypeScript error arises when accessing object properties that might not exist, especially in schemas where `additionalProperties` are allowed or when properties are optional. It's often exacerbated if `noUncheckedIndexedAccess` is not enabled.

fix

Enable `"noUncheckedIndexedAccess": true` in your `tsconfig.json`. Alternatively, use optional chaining (`?.`), nullish coalescing (`??`), or explicit `if` checks to safely access properties.

TS2339: Property 'client' does not exist on type 'Options'.

This error typically occurs in programmatic usage when attempting to access a 'client' property on an `Options` object, which is not part of the standard `openapi-typescript` programmatic API. It might be an attempt to use a feature from a different OpenAPI generation tool or an older, incompatible API version.

fix

Review the programmatic usage documentation for `openapi-typescript` (e.g., `import openapiTS from 'openapi-typescript'; await openapiTS(input);`). If using `@hey-api/openapi-ts`, ensure you're using `createClient` correctly with its specific configuration.

Error: "The OpenAPI document has an invalid version."

The input OpenAPI schema specifies a version other than 3.0 or 3.1, such as 2.x (Swagger), which is no longer supported by recent versions of `openapi-typescript`.

fix

Update your OpenAPI specification to version 3.0 or 3.1. If this is not possible, downgrade `openapi-typescript` to a 5.x version, which supports OpenAPI 2.x schemas.

Upgrade

Version history

7.13.0latest on npm

Audit

Dependencies

typescriptrequiredRequired as a peer dependency for consuming the generated types and for the library's internal TypeScript usage.

Agent activity

32 hits · last 30 days

node

Resources

githubhttps://github.com/openapi-ts/openapi-typescript ↗

packagehttps://www.npmjs.com/package/openapi-typescript ↗

homepagehttps://openapi-ts.dev ↗