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

Setup

This library requires the latest version of Node.js installed (20.x or higher recommended). With that present, run the following in your project:

npm i -D openapi-typescript typescript

✨ Tip

Enabling noUncheckedIndexedAccess in tsconfig.json can go along way to improve type safety (read more)

Basic 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 type { paths, components } from "./api/v1"; // 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!

📓 Docs

View Docs