96 lines
3.1 KiB
Plaintext
96 lines
3.1 KiB
Plaintext
<img src="../../docs/public/assets/openapi-ts.svg" alt="openapi-typescript" width="200" height="40" />
|
||
|
||
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](./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](./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:
|
||
|
||
```diff
|
||
{
|
||
"compilerOptions": {
|
||
+ "module": "ESNext", // or "NodeNext"
|
||
+ "moduleResolution": "Bundler" // or "NodeNext"
|
||
}
|
||
}
|
||
```
|
||
|
||
> **Highly recommended**
|
||
>
|
||
> Also adding the following can boost type safety:
|
||
> ```diff
|
||
> {
|
||
> "compilerOptions": {
|
||
> + "noUncheckedIndexedAccess": true
|
||
> }
|
||
> }
|
||
> ```
|
||
|
||
## 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:
|
||
|
||
```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](https://openapi-ts.dev/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.)
|
||
|
||
## 📓 Docs
|
||
|
||
[View Docs](https://openapi-ts.dev/)
|