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](./LICENSE) 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](./examples/) ## Usage First, generate a local type file by running `npx openapi-typescript`: ```bash # 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: ```ts 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 ```bash 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](https://github.com/sharmarajdaksh)!_ #### ☁️ Remote schemas ```bash 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](https://github.com/psmyrdek)!_ #### ⚾ Fetching data Fetching data can be done simply and safely using an **automatically-typed fetch wrapper**: - [openapi-fetch](https://github.com/drwpow/openapi-fetch) (recommended) - [openapi-typescript-fetch](https://www.npmjs.com/package/openapi-typescript-fetch) by [@ajaishankar](https://github.com/ajaishankar) **Example** ([openapi-fetch](https://github.com/drwpow/openapi-fetch)) ```ts import createClient from "openapi-fetch"; import { paths } from "./v1"; // (generated from openapi-typescript) const { get, post, put, patch, del } = createClient({ 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: ```ts export interface paths { "/user/{user_id}": components["schemas"]["User"]; } ``` Which means your type lookups also have to match the exact URL: ```ts 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: ```ts 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](https://github.com/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: ```yaml components: schemas: TupleType type: array items: type: string minItems: 1 maxItems: 2 ``` Enabling `--support-array-length` would change the typing like so: ```diff 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](https://github.com/kgtkr)!_ ### 🐢 Node ```bash npm i --save-dev openapi-typescript ``` ```js 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](#--options) 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: ```yaml 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: ```js 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: ```diff - updated_at?: string; + updated_at?: Date; ``` Any [Schema Object](https://spec.openapis.org/oas/latest.html#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 1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated. 1. Generate **runtime-free types** for maximum performance. 1. This library does **NOT** validate your schema, there existing libraries for that (like [`redocly lint`](https://redocly.com/docs/cli/commands/lint/)). 1. The generated TypeScript types **must** match your schema as closely as possible (e.g. no renaming to `PascalCase`) 1. This library should never require Java, node-gyp, or some other complex environment to work. This should require Node.js and nothing else. 1. This library will never require a running OpenAPI server to work. ## 🤝 Contributing PRs are welcome! Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) guide.

	Stars	Issues	Version	Updated	Created
openapi-typescript	3,000	50	6.2.6	2 days ago	3 years ago
openapi-typescript-codegen	1,637	154	0.24.0	2 months ago	4 years ago
swagger-client	2,495	55	3.19.8	4 days ago	10 years ago
swagger-codegen	1	145	0.1.1	7 years ago	7 years ago

openapi-typescript vs openapi-typescript-codegen vs swagger-client vs swagger-codegen

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past