## File: README.md
# openapi-typescript
Tools for consuming OpenAPI schemas in TypeScript.
## 📦 Packages
Generate TypeScript types from static OpenAPI schemas
Ultra-fast fetching for TypeScript generated automatically from your OpenAPI schema.
## ⭐ Sponsors
### 🥇 Gold Sponsors
### 🥈 Silver Sponsors
### Backers
Become a sponsor by supporting this project on [OpenCollective](https://opencollective.com/openapi-ts)!
## 🤝 Contributing
Contributions are appreciated and welcome! See the appropriate guide for each package:
- [Contributing to openapi-typescript](./packages/openapi-typescript/CONTRIBUTING.md)
- [Contributing to openapi-fetch](./packages/openapi-fetch/CONTRIBUTING.md)
- [Contributing to docs](./docs/CONTRIBUTING.md)
## ♥️ Thanks
- Thanks to [the Project Sponsors](#-sponsors) for keeping this project going!
- Thanks to [dozens of lovely, smart contributors](https://github.com/openapi-ts/openapi-typescript/graphs/contributors) that made this library possible
- Thanks to [Vitepress](https://vitepress.dev/) for the docs site
- Thanks to [Cloudflare Pages](https://pages.cloudflare.com/) for docs site hosting
- Thanks to [Algolia](https://www.algolia.com/) for the docs site search
---
## File: docs/index.md
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
hero:
name: "OpenAPI TypeScript"
tagline: Convert OpenAPI 3.0/3.1 schemas to TypeScript types and create type-safe fetching.
actions:
- theme: brand
text: Get Started
link: /introduction
- theme: alt
text: View on GitHub
link: https://github.com/openapi-ts/openapi-typescript
features:
- title: Blazing Fast
details: Nothing is faster than instant. Static TypeScript types provide zero runtime cost and zero client weight.
- title: Type-safe
details: Use your OpenAPI schema to typecheck your entire codebase with no setup and no tests.
- title: Works anywhere
details: Runs anywhere TypeScript does. Works for any stack and any framework.
---
### Used by
### Sponsors
Become a sponsor by supporting this project on [OpenCollective](https://opencollective.com/openapi-ts)!
[](https://opencollective.com/openapi-ts/donate)
---
## File: docs/README.md
# openapi-typescript Docs
Docs site powered by [Vitepress](https://vitepress.dev/), an ergonomic docs site template powered by Vite.
Lives at [https://openapi-ts.dev](https://openapi-ts.dev).
## Setup
Setup requires the latest version of [Node.js](https://nodejs.org/en) and [pnpm](https://pnpm.io/). With both installed, run:
```
pnpm i
pnpm run dev
```
That will launch the docs site at `http://localhost:5173`.
## Editing
All content lives in `.md` files that feature normal Markdown content [with powerful Vitepress extensions](https://vitepress.dev/guide/markdown).
## Contributing
Docs contributions are welcome! Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for additional assistance.
---
## File: docs/introduction.md
---
title: openapi-typescript
---
openapi-typescript turns [OpenAPI 3.0 & 3.1](https://spec.openapis.org/oas/latest.html) schemas into TypeScript quickly using Node.js. No Java/node-gyp/running OpenAPI servers necessary.
The code is [MIT-licensed](https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-typescript/LICENSE) and free for use.
::: tip
New to OpenAPI? Speakeasy’s [Intro to OpenAPI](https://www.speakeasyapi.dev/openapi) is an accessible guide to newcomers that explains the “why” and “how” of OpenAPI.
:::
## Features
- ✅ Supports OpenAPI 3.0 and 3.1 (including advanced features like [discriminators](https://spec.openapis.org/oas/v3.1.0#discriminator-object))
- ✅ Generate **runtime-free types** that outperform old school codegen
- ✅ Load schemas from YAML or JSON, locally or remotely
- ✅ Generate types for even huge schemas within milliseconds
_Note: OpenAPI 2.x is supported with versions `5.x` and previous_
## Examples
👀 [See examples](https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-typescript/examples/)
## Setup
This library requires the latest version of [Node.js](https://nodejs.org) installed (20.x or higher recommended). With that present, run the following in your project:
```bash
npm i -D openapi-typescript typescript
```
And in your `tsconfig.json`, to load the types properly:
::: code-group
```json [tsconfig.json]
{
"compilerOptions": {
"module": "ESNext", // or "NodeNext" // [!code ++]
"moduleResolution": "Bundler" // or "NodeNext" // [!code ++]
}
}
```
:::
::: tip Highly recommended
Also adding the following can boost type safety:
::: code-group
```json [tsconfig.json]
{
"compilerOptions": {
"noUncheckedIndexedAccess": true // [!code ++]
}
}
```
:::
## Basic usage
First, generate a local type file by running `npx openapi-typescript`, first specifying your input schema (JSON or YAML), and where you’d like the `--output` (`-o`) to be saved:
```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]
```
Then in your TypeScript project, import types where needed:
::: code-group
```ts [src/my-project.ts]
import type { paths, components } from "./my-openapi-3-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"];
```
:::
From here, you can use these types for any of the following (but not limited to):
- Using an OpenAPI-supported fetch client (like [openapi-fetch](/openapi-fetch/))
- Asserting types for other API requestBodies and responses
- Building core business logic based on API types
- Validating mock test data is up-to-date with the current schema
- Packaging API types into any npm packages you publish (such as client SDKs, etc.)