Skip to content


The CLI is the most common way to use openapi-typescript. The CLI can parse JSON and YAML, and even validates your schemas using the Redocly CLI. It can parse local and remote schemas (and even supports basic auth).

Transforming an OpenAPI schema to TypeScript

Single schema

The simplest way to transform schemas is by specifying an input schema (JSON or YAML), followed by --output (-o) where you’d like the output to be saved:

npx openapi-typescript schema.yaml -o schema.ts

# 🚀 schema.yaml -> schema.ts [50ms]
npx openapi-typescript -o petstore.d.ts

# 🚀 -> petstore.d.ts [250ms]

Multiple schemas

To transform multiple schemas, create a redocly.yaml file in the root of your project with APIs defined. Under apis, give each schema a unique name and optionally a version (the name doesn’t matter, so long as it’s unique). Set the root value to your schema’s entry point—this will act as the main input. For the output, set it with x-openapi-ts.output:

    root: ./openapi/openapi.yaml
      output: ./openapi/openapi.ts
    root: ./openapi/external.yaml
      output: ./openapi/external.ts


This will preserve schemas 1:1 input:output. To bundle multiple schemas into one, use Redocly’s bundle command

Whenever you have a redocly.yaml file in your project with apis, you can omit the input/output parameters in the CLI:

npx openapi-typescript


In previous versions globbing was supported, but that has been deprecated in v7 in favor of redocly.yaml. You’ll be able to control per-schema output locations better, as well as getting unique per-schema settings.

Redoc config

A redocly.yaml file isn’t required to use openapi-typescript. By default it extends the "minimal" built-in config. But it is recommended if you want to have custom validation rules (or build types for multiple schemas). The CLI will try to automatically find a redocly.yaml in the root of your project, but you can also provide its location with the --redoc flag:

npx openapi-typescript --redoc ./path/to/redocly.yaml

You can read more about the Redoc’s configuration options in their docs.


Authentication for non-public schemas is handled in your Redocly config. You can add headers and basic authentication like so:

      - matches:**
        name: X-API-KEY
        envVariable: SECRET_KEY
      - matches:*/test.yaml
        name: Authorization
        envVariable: SECRET_AUTH

Refer to the Redocly docs for additional options.


The following flags are supported in the CLI:

--helpDisplay inline help message and exit
--versionDisplay this library’s version and exit
--output [location]-o(stdout)Where should the output file be saved?
--redoc [location]Path to a redocly.yaml file (see Multiple schemas)
--additional-propertiesfalseAllow arbitrary properties for all schema objects without additionalProperties: false
--alphabetizefalseSort types alphabetically
--array-lengthfalseGenerate tuples using array minItems / maxItems
--default-non-nullabletrueTreat schema objects with default values as non-nullable (with the exception of parameters)
--properties-required-by-defaultfalseTreat schema objects without required as having all properties required.
--empty-objects-unknownfalseAllow arbitrary properties for schema objects with no specified properties, and no specified additionalProperties
--enumfalseGenerate true TS enums rather than string unions.
--enum-valuesfalseExport enum values as arrays.
--exclude-deprecatedfalseExclude deprecated fields from types
--export-type-tfalseExport type instead of interface
--immutablefalseGenerates immutable types (readonly properties and readonly array)
--path-params-as-typesfalseAllow dynamic string lookups on the paths object


By default, your URLs are preserved exactly as-written in your schema:

export interface paths {
  "/user/{user_id}": components["schemas"]["User"];

Which means your type lookups also have to match the exact URL:

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

const url = `/user/${id}`;
type UserResponses = paths["/user/{user_id}"]["responses"];

But when --path-params-as-types is enabled, you can take advantage of dynamic lookups like so:

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

const url = `/user/${id}`;
type UserResponses = paths[url]["responses"]; // automatically matches `paths['/user/{user_id}']`

Though this is a contrived example, you could use this feature to automatically infer typing based on the URL in a fetch client or in some other useful place in your application.

Thanks, @Powell-v2!


This option is useful for generating tuples if an array type specifies minItems or maxItems.

For example, given the following schema:

      type: array
        type: string
      minItems: 1
      maxItems: 2

Enabling --array-length would change the typing like so:

export interface components {
  schemas: {
    TupleType: string[]; 
    TupleType: [string] | [string, string]; 

This results in more explicit typechecking of array lengths.

Note: this has a reasonable limit, so for example maxItems: 100 would simply flatten back down to string[];

Thanks, @kgtkr!