openapi-typescript

What is openapi-typescript?

The openapi-typescript npm package is a tool that generates TypeScript types from OpenAPI specifications. This helps developers ensure type safety and better integration between their API definitions and TypeScript code.

What are openapi-typescript's main functionalities?

Generate TypeScript Types

This feature allows you to generate TypeScript types from an OpenAPI specification URL. The generated types are then saved to a file named 'types.ts'.

const openapiTS = require('openapi-typescript');
const fs = require('fs');

async function generateTypes() {
  const types = await openapiTS('https://api.example.com/openapi.json');
  fs.writeFileSync('types.ts', types);
}

generateTypes();

Generate Types from Local File

This feature allows you to generate TypeScript types from a local OpenAPI specification file. The generated types are saved to a file named 'types.ts'.

const openapiTS = require('openapi-typescript');
const fs = require('fs');
const path = require('path');

async function generateTypes() {
  const types = await openapiTS(path.join(__dirname, 'openapi.json'));
  fs.writeFileSync('types.ts', types);
}

generateTypes();

Custom Type Generation Options

This feature allows you to customize the type generation process by providing options such as a transform function. The transform function can be used to modify the schema before generating the types.

const openapiTS = require('openapi-typescript');
const fs = require('fs');

async function generateTypes() {
  const types = await openapiTS('https://api.example.com/openapi.json', {
    transform: (schema) => {
      // Custom transformation logic
      return schema;
    }
  });
  fs.writeFileSync('types.ts', types);
}

generateTypes();

Other packages similar to openapi-typescript

swagger-typescript-api

The swagger-typescript-api package generates TypeScript API client code from Swagger/OpenAPI definitions. It provides more advanced features like generating API client methods and supports both Swagger 2.0 and OpenAPI 3.0 specifications.

typescript-fetch

The typescript-fetch package is a generator for TypeScript clients using the Fetch API. It generates TypeScript code from OpenAPI specifications and is particularly useful for creating client-side code that interacts with RESTful APIs.

README

openapi-typescript generates TypeScript types from static OpenAPI schemas quickly using only Node.js. It is fast, lightweight, (almost) dependency-free, and no Java/node-gyp/running OpenAPI servers necessary.

The code is MIT-licensed and free for use.

Features

• ✅ Supports OpenAPI 3.0 and 3.1 (including advanced features like discriminators)
• ✅ Generate runtime-free types that outperform old-school codegen
• ✅ Load schemas from YAML or JSON, locally or remotely
• ✅ Native Node.js code is fast and generates types within milliseconds

Examples

👀 See examples

Usage

First, generate a local type file by running npx openapi-typescript:

# Local schema
npx openapi-typescript ./path/to/my/schema.yaml -o ./path/to/my/schema.d.ts
# 🚀 ./path/to/my/schema.yaml -> ./path/to/my/schema.d.ts [7ms]

# Remote schema
npx openapi-typescript https://myapi.dev/api/v1/openapi.yaml -o ./path/to/my/schema.d.ts
# 🚀 https://myapi.dev/api/v1/openapi.yaml -> ./path/to/my/schema.d.ts [250ms]

⚠️ Be sure to validate your schemas! openapi-typescript will err on invalid schemas.

Then, import schemas from the generated file like so:

import { paths, components } from "./path/to/my/schema"; // <- generated by openapi-typescript

// Schema Obj
type MyType = components["schemas"]["MyType"];

// Path params
type EndpointParams = paths["/my/endpoint"]["parameters"];

// Response obj
type SuccessResponse = paths["/my/endpoint"]["get"]["responses"][200]["content"]["application/json"]["schema"];
type ErrorResponse = paths["/my/endpoint"]["get"]["responses"][500]["content"]["application/json"]["schema"];

🦠 Globbing local schemas

npx openapi-typescript "specs/**/*.yaml" --output schemas/

# 🚀 specs/one.yaml -> schemas/specs/one.ts [7ms]
# 🚀 specs/two.yaml -> schemas/specs/two.ts [7ms]
# 🚀 specs/three.yaml -> schemas/specs/three.ts [7ms]

Thanks, @sharmarajdaksh!

☁️ Remote schemas

npx openapi-typescript https://petstore3.swagger.io/api/v3/openapi.yaml --output petstore.d.ts

# 🚀 https://petstore3.swagger.io/api/v3/openapi.yaml -> petstore.d.ts [250ms]

Thanks, @psmyrdek!

⚾ Fetching data

Fetching data can be done simply and safely using an automatically-typed fetch wrapper:

• openapi-fetch (recommended)
• openapi-typescript-fetch by @ajaishankar

Example (openapi-fetch)

import createClient from "openapi-fetch";
import { paths } from "./v1"; // (generated from openapi-typescript)

const { get, post, put, patch, del } = createClient<paths>({
  baseUrl: "https://myserver.com/api/v1/",
  headers: {
    Authorization: `Bearer ${import.meta.env.VITE_AUTH_TOKEN}`,
  },
});

See each project’s respective pages for usage & install instructions.

✨ Tip

A good fetch wrapper should never use generics. Generics require more typing and can hide errors!

📖 Options

The following flags can be appended to the CLI command.

Option	Alias	Default	Description
--help			Display inline help message and exit
--version			Display this library’s version and exit
--output [location]	-o	(stdout)	Where should the output file be saved?
--auth [token]			Provide an auth token to be passed along in the request (only if accessing a private schema)
--header	-x		Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the key: value pattern
--headers-object="{…}"	-h		Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over --header
--http-method	-m	GET	Provide the HTTP Verb/Method for fetching a schema from a remote URL
--immutable-types		false	Generates immutable types (readonly properties and readonly array)
--additional-properties		false	Allow arbitrary properties for all schema objects without additionalProperties: false
--empty-objects-unknown		false	Allow arbitrary properties for schema objects with no specified properties, and no specified additionalProperties
--default-non-nullable		false	Treat schema objects with default values as non-nullable
--export-type	-t	false	Export type instead of interface
--path-params-as-types		false	Allow dynamic string lookups on the paths object
--support-array-length		false	Generate tuples using array minItems / maxItems
--alphabetize		false	Sort types alphabetically
--exclude-deprecated		false	Exclude deprecated fields from types

🚩 --path-params-as-types

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 { paths } from "./my-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 { paths } from "./my-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!

🚩 --support-array-length

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

For example, given the following schema:

components:
  schemas:
    TupleType
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 2

Enabling --support-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!

🐢 Node

npm i --save-dev openapi-typescript

import fs from "node:fs";
import openapiTS from "openapi-typescript";

// example 1: load [object] as schema (JSON only)
const schema = await fs.promises.readFile("spec.json", "utf8"); // must be OpenAPI JSON
const output = await openapiTS(JSON.parse(schema));

// example 2: load [string] as local file (YAML or JSON; released in v4.0)
const localPath = new URL("./spec.yaml", import.meta.url); // may be YAML or JSON format
const output = await openapiTS(localPath);

// example 3: load [string] as remote URL (YAML or JSON; released in v4.0)
const output = await openapiTS("https://myurl.com/v1/openapi.yaml");

⚠️ Note that unlike the CLI, YAML isn’t supported in the Node.js API. You’ll need to convert it to JSON yourself using js-yaml first.

📖 Node options

The Node API supports all the CLI flags above in camelCase format, plus the following additional options:

Name	Type	Default	Description
commentHeader	string		Override the default “This file was auto-generated …” file heading
inject	string		Inject arbitrary TypeScript types into the start of the file
transform	Function		Override the default Schema Object ➝ TypeScript transformer in certain scenarios
postTransform	Function		Same as transform but runs after the TypeScript transformation

🤖 transform / postTransform

Use the transform() and postTransform() options to override the default Schema Object transformer with your own. This is useful for providing non-standard modifications for specific parts of your schema.

• transform() runs BEFORE the conversion to TypeScript (you’re working with the original OpenAPI nodes)
• postTransform() runs AFTER the conversion to TypeScript (you’re working with TypeScript types)

For example, say your schema has the following property:

properties:
  updated_at:
    type: string
    format: date-time

By default, openapiTS will generate updated_at?: string; because it’s not sure which format you want by "date-time" (formats are nonstandard and can be whatever you’d like). But we can enhance this by providing our own custom formatter, like so:

const types = openapiTS(mySchema, {
  transform(schemaObject, metadata): string {
    if ("format" in schemaObject && schemaObject.format === "date-time") {
      return schemaObject.nullable ? "Date | null" : "Date";
    }
  },
});

That would result in the following change:

-  updated_at?: string;
+  updated_at?: Date;

Another common transformation is for file uploads, where the body of a request is a multipart/form-data with some Blob fields. Here's an example schema:

Body_file_upload:
  type: object;
  properties:
    file:
      type: string;
      format: binary;
    }
  }
}

Use the same pattern to transform the types:

const types = openapiTS(mySchema, {
  transform(schemaObject, metadata): string {
    if ("format" in schemaObject && schemaObject.format === "binary") {
      return schemaObject.nullable ? "Blob | null" : "Blob";
    }
  },
});

Resultant diff with correctly-typed file property:

-    file?: string;
+    file?: Blob;

Any Schema Object present in your schema will be run through this formatter (even remote ones!). Also be sure to check the metadata parameter for additional context that may be helpful.

There are many other uses for this besides checking format. Because this must return a string you can produce any arbitrary TypeScript code you’d like (even your own custom types).

🏅 Project Goals

• Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
• Generate runtime-free types for maximum performance.
• This library does NOT validate your schema, there existing libraries for that (like redocly lint).
• The generated TypeScript types must match your schema as closely as possible (e.g. no renaming to PascalCase)
• This library should never require Java, node-gyp, or some other complex environment to work. This should require Node.js and nothing else.
• This library will never require a running OpenAPI server to work.

🤝 Contributing

PRs are welcome! Please see our CONTRIBUTING.md guide.