OpenAPI to TypeScript Type Generator

Common errors

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

  cause 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'.

  cause 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'.

  cause 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."

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

Warnings

• breaking OpenAPI 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.
• breaking Version 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.
• gotcha For 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`.
• gotcha To 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"`.
• gotcha The `--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.

Install

• npm install openapi-typescript npm
• yarn add openapi-typescript yarn
• pnpm add openapi-typescript pnpm

Imports

• openapiTS
  wrong:

  import { openapiTS } from 'openapi-typescript';

  correct:

  import openapiTS from 'openapi-typescript';

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

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

  correct:

  import type { 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
  wrong:

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

  correct:

  import type { 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.

Quickstart

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();