From 3abf019daa3d97620656601c800b1a4475dbebdd Mon Sep 17 00:00:00 2001 From: phk422 <1769476785@qq.com> Date: Mon, 8 Jul 2024 20:01:58 +0800 Subject: [PATCH 1/4] fix(docs): Document inconsistency --- packages/openapi-typescript/README.md | 95 ++++++++++++++++----------- 1 file changed, 56 insertions(+), 39 deletions(-) diff --git a/packages/openapi-typescript/README.md b/packages/openapi-typescript/README.md index 6e1a15e6f..eb3792ab0 100644 --- a/packages/openapi-typescript/README.md +++ b/packages/openapi-typescript/README.md @@ -1,53 +1,86 @@ openapi-typescript -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. +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. +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) -- ✅ Generate **runtime-free types** that outperform old-school codegen +- ✅ 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 -- ✅ Native Node.js code is fast and generates types within milliseconds +- ✅ Generate types for even huge schemas within milliseconds + +_Note: OpenAPI 2.x is supported with versions `5.x` and previous_ ## Examples -👀 [See examples](./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 installed (20.x or higher recommended). With that present, run the following in your project: +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 ``` -> ✨ **Tip** -> -> Enabling [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) in `tsconfig.json` can go along way to improve type safety ([read more](../../docs/src/content/docs/advanced.md#enable-nouncheckedindexedaccess-in-your-tsconfigjson)) +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, 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] -``` -```bash # 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 in your TypeScript project, import types where needed: -Then, import schemas from the generated file like so: +::: code-group -```ts +```ts [src/my-project.ts] import type { paths, components } from "./my-openapi-3-schema"; // generated by openapi-typescript // Schema Obj @@ -63,28 +96,12 @@ 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)!_ +::: -## 📓 Docs +From here, you can use these types for any of the following (but not limited to): -[View Docs](https://openapi-ts.dev/) +- 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.) From a598c464902de46f114be6408f18108e73573ef6 Mon Sep 17 00:00:00 2001 From: phk422 <1769476785@qq.com> Date: Tue, 9 Jul 2024 11:10:35 +0800 Subject: [PATCH 2/4] docs: format --- packages/openapi-typescript/README.md | 47 +++++++++------------------ 1 file changed, 16 insertions(+), 31 deletions(-) diff --git a/packages/openapi-typescript/README.md b/packages/openapi-typescript/README.md index eb3792ab0..bcb40edf7 100644 --- a/packages/openapi-typescript/README.md +++ b/packages/openapi-typescript/README.md @@ -4,11 +4,8 @@ openapi-typescript turns [OpenAPI 3.0 & 3.1](https://spec.openapis.org/oas/lates 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. - -::: +> **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 @@ -33,34 +30,26 @@ npm i -D openapi-typescript typescript And in your `tsconfig.json`, to load the types properly: -::: code-group - -```json [tsconfig.json] +```diff [tsconfig.json] { "compilerOptions": { - "module": "ESNext", // or "NodeNext" // [!code ++] - "moduleResolution": "Bundler" // or "NodeNext" // [!code ++] ++ "module": "ESNext", // or "NodeNext" ++ "moduleResolution": "Bundler" // or "NodeNext" } } ``` -::: - -::: tip Highly recommended - -Also adding the following can boost type safety: - -::: code-group - -```json [tsconfig.json] -{ - "compilerOptions": { - "noUncheckedIndexedAccess": true // [!code ++] - } -} -``` - -::: +> **Tip:** +> **Highly recommended** +> +> Also adding the following can boost type safety: +> ```diff [tsconfig.json] +> { +> "compilerOptions": { +> + "noUncheckedIndexedAccess": true +> } +> } +> ``` ## Basic usage @@ -78,8 +67,6 @@ npx openapi-typescript https://myapi.dev/api/v1/openapi.yaml -o ./path/to/my/sch 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 @@ -96,8 +83,6 @@ 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/)) From 7f76e4b679b4be370c887f3989e4fac017bd40fc Mon Sep 17 00:00:00 2001 From: phk422 <1769476785@qq.com> Date: Tue, 9 Jul 2024 11:21:15 +0800 Subject: [PATCH 3/4] docs: Document consistency --- packages/openapi-fetch/README.md | 74 ++++++++++++++++++++++++-------- 1 file changed, 57 insertions(+), 17 deletions(-) diff --git a/packages/openapi-fetch/README.md b/packages/openapi-fetch/README.md index d8ba284f8..2b58a96a7 100644 --- a/packages/openapi-fetch/README.md +++ b/packages/openapi-fetch/README.md @@ -1,6 +1,6 @@ openapi-fetch -openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Weighs **4 kB** and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS. +openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Weighs **5 kb** and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS. | Library | Size (min) | “GET” request\* | | :------------------------- | ---------: | :------------------------- | @@ -12,9 +12,9 @@ openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Wei _\* [Benchmarks are approximate](https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-fetch/test/index.bench.js) to just show rough baseline and will differ among machines and browsers. The relative performance between libraries is more reliable._ -The syntax is inspired by popular libraries like react-query or Apollo client, but without all the bells and whistles and in a 2 kB package. +The syntax is inspired by popular libraries like react-query or Apollo client, but without all the bells and whistles and in a 5 kb package. -```ts +```ts [src/my-project.ts] import createClient from "openapi-fetch"; import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript @@ -36,9 +36,9 @@ await client.PUT("/blogposts", { }); ``` -`data` and `error` are typechecked and expose their shapes to Intellisense in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch. +`data` and `error` are typechecked and expose their shapes to Intellisence in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch. -`GET`, `PUT`, `POST`, etc. are only thin wrappers around the native [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (which you can [swap for any call](https://openapi-ts.dev/openapi-fetch/api/#create-client)). +`GET()`, `PUT()`, `POST()`, etc. are thin wrappers around the native [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (which you can [swap for any call](/openapi-fetch/api#create-client)). Notice there are no generics, and no manual typing. Your endpoint’s request and response were inferred automatically. This is a huge improvement in the type safety of your endpoints because **every manual assertion could lead to a bug**! This eliminates all of the following: @@ -49,16 +49,19 @@ Notice there are no generics, and no manual typing. Your endpoint’s request an - ✅ Also eliminates `as` type overrides that can also hide bugs - ✅ All of this in a **5 kb** client package 🎉 -## 🔧 Setup +## Setup -Install this library along with [openapi-typescript](../openapi-typescript): +Install this library along with [openapi-typescript](/introduction): ```bash npm i openapi-fetch npm i -D openapi-typescript typescript ``` -> **Highly recommended**: enable [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) in your `tsconfig.json` ([docs](/advanced#enable-nouncheckedindexaccess-in-your-tsconfigjson)) +> **TIP:** +> **Highly recommended** +> +> Enable [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) in your `tsconfig.json` ([docs](/advanced#enable-nouncheckedindexaccess-in-your-tsconfigjson)) Next, generate TypeScript types from your OpenAPI schema using openapi-typescript: @@ -66,11 +69,9 @@ Next, generate TypeScript types from your OpenAPI schema using openapi-typescrip npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts ``` -> ⚠️ Be sure to validate your schemas! openapi-typescript will err on invalid schemas. - -Lastly, be sure to **run typechecking** in your project. This can be done by adding `tsc --noEmit` to your npm scripts like so: +Lastly, be sure to **run typechecking** in your project. This can be done by adding `tsc --noEmit` to your [npm scripts](https://docs.npmjs.com/cli/v9/using-npm/scripts) like so: -```json +```json [package.json] { "scripts": { "test:ts": "tsc --noEmit" @@ -80,15 +81,17 @@ Lastly, be sure to **run typechecking** in your project. This can be done by add And run `npm run test:ts` in your CI to catch type errors. -> **Tip**: use `tsc --noEmit` to check for type errors rather than relying on your linter or your build command. Nothing will typecheck as accurately as the TypeScript compiler itself. +> **TIP:** +> +> Use `tsc --noEmit` to check for type errors rather than relying on your linter or your build command. Nothing will typecheck as accurately as the TypeScript compiler itself. -## Usage +## Basic usage The best part about using openapi-fetch over oldschool codegen is no documentation needed. openapi-fetch encourages using your existing OpenAPI documentation rather than trying to find what function to import, or what parameters that function wants: ![OpenAPI schema example](../../docs/public/assets/openapi-schema.png) -```ts +```ts [src/my-project.ts] import createClient from "openapi-fetch"; import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript @@ -114,6 +117,43 @@ const { data, error } = await client.PUT("/blogposts", { 2. You pass in your desired `path` to `GET()`, `PUT()`, etc. 3. TypeScript takes over the rest and returns helpful errors for anything missing or invalid -## 📓 Docs +### Pathname + +The pathname of `GET()`, `PUT()`, `POST()`, etc. **must match your schema literally.** Note in the example, the URL is `/blogposts/{post_id}`. This library will quickly replace all `path` params for you (so they can be typechecked). + + +> **TIP:** +> +> openapi-fetch infers types from the URL. Prefer static string values over dynamic runtime values, e.g.: +> - ✅ `"/blogposts/{post_id}"` +> - ❌ `[...pathParts].join("/") + "{post_id}"` + +This library also supports the **label** and **matrix** serialization styles as well ([docs](https://swagger.io/docs/specification/serialization/#path)) automatically. + +### Request + +The `GET()` request shown needed the `params` object that groups [parameters by type](https://spec.openapis.org/oas/latest.html#parameter-object) (`path` or `query`). If a required param is missing, or the wrong type, a type error will be thrown. + +The `POST()` request required a `body` object that provided all necessary [requestBody](https://spec.openapis.org/oas/latest.html#request-body-object) data. + +### Response + +All methods return an object with **data**, **error**, and **response**. + +```ts +const { data, error, response } = await client.GET("/url"); +``` + +| Object | Response | +| :--------- | :-------------------------------------------------------------------------------------------------------------------------- | +| `data` | `2xx` response if OK; otherwise `undefined` | +| `error` | `5xx`, `4xx`, or `default` response if not OK; otherwise `undefined` | +| `response` | [The original Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) which contains `status`, `headers`, etc. | + +## Support -[View Docs](https://openapi-ts.dev/openapi-fetch/) +| Platform | Support | +| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Browsers** | [See fetch API support](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API#browser_compatibility) (widely-available in all major browsers) | +| **Node** | >= 18.0.0 | +| **TypeScript** | >= 4.7 (>= 5.0 recommended) | From 3ca8e9430dcf3a56fe228bc55967d8897adf9b0f Mon Sep 17 00:00:00 2001 From: phk422 Date: Tue, 16 Jul 2024 17:00:15 +0800 Subject: [PATCH 4/4] docs: update --- docs/openapi-fetch/index.md | 2 +- packages/openapi-fetch/README.md | 54 ++++----------------------- packages/openapi-typescript/README.md | 17 +++++---- 3 files changed, 19 insertions(+), 54 deletions(-) diff --git a/docs/openapi-fetch/index.md b/docs/openapi-fetch/index.md index 1a0819733..619c7d9c1 100644 --- a/docs/openapi-fetch/index.md +++ b/docs/openapi-fetch/index.md @@ -44,7 +44,7 @@ await client.PUT("/blogposts", { ::: -`data` and `error` are typechecked and expose their shapes to Intellisence in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch. +`data` and `error` are typechecked and expose their shapes to Intellisense in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch. `GET()`, `PUT()`, `POST()`, etc. are thin wrappers around the native [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (which you can [swap for any call](/openapi-fetch/api#create-client)). diff --git a/packages/openapi-fetch/README.md b/packages/openapi-fetch/README.md index 2b58a96a7..c6891f0c5 100644 --- a/packages/openapi-fetch/README.md +++ b/packages/openapi-fetch/README.md @@ -14,7 +14,7 @@ _\* [Benchmarks are approximate](https://github.com/openapi-ts/openapi-typescrip The syntax is inspired by popular libraries like react-query or Apollo client, but without all the bells and whistles and in a 5 kb package. -```ts [src/my-project.ts] +```ts import createClient from "openapi-fetch"; import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript @@ -36,9 +36,9 @@ await client.PUT("/blogposts", { }); ``` -`data` and `error` are typechecked and expose their shapes to Intellisence in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch. +`data` and `error` are typechecked and expose their shapes to Intellisense in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch. -`GET()`, `PUT()`, `POST()`, etc. are thin wrappers around the native [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (which you can [swap for any call](/openapi-fetch/api#create-client)). +`GET()`, `PUT()`, `POST()`, etc. are thin wrappers around the native [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (which you can [swap for any call](https://openapi-ts.dev/openapi-fetch/api/#create-client)). Notice there are no generics, and no manual typing. Your endpoint’s request and response were inferred automatically. This is a huge improvement in the type safety of your endpoints because **every manual assertion could lead to a bug**! This eliminates all of the following: @@ -51,14 +51,13 @@ Notice there are no generics, and no manual typing. Your endpoint’s request an ## Setup -Install this library along with [openapi-typescript](/introduction): +Install this library along with [openapi-typescript](../openapi-typescript): ```bash npm i openapi-fetch npm i -D openapi-typescript typescript ``` -> **TIP:** > **Highly recommended** > > Enable [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) in your `tsconfig.json` ([docs](/advanced#enable-nouncheckedindexaccess-in-your-tsconfigjson)) @@ -71,7 +70,7 @@ npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts Lastly, be sure to **run typechecking** in your project. This can be done by adding `tsc --noEmit` to your [npm scripts](https://docs.npmjs.com/cli/v9/using-npm/scripts) like so: -```json [package.json] +```json { "scripts": { "test:ts": "tsc --noEmit" @@ -91,7 +90,7 @@ The best part about using openapi-fetch over oldschool codegen is no documentati ![OpenAPI schema example](../../docs/public/assets/openapi-schema.png) -```ts [src/my-project.ts] +```ts import createClient from "openapi-fetch"; import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript @@ -117,43 +116,6 @@ const { data, error } = await client.PUT("/blogposts", { 2. You pass in your desired `path` to `GET()`, `PUT()`, etc. 3. TypeScript takes over the rest and returns helpful errors for anything missing or invalid -### Pathname - -The pathname of `GET()`, `PUT()`, `POST()`, etc. **must match your schema literally.** Note in the example, the URL is `/blogposts/{post_id}`. This library will quickly replace all `path` params for you (so they can be typechecked). - - -> **TIP:** -> -> openapi-fetch infers types from the URL. Prefer static string values over dynamic runtime values, e.g.: -> - ✅ `"/blogposts/{post_id}"` -> - ❌ `[...pathParts].join("/") + "{post_id}"` - -This library also supports the **label** and **matrix** serialization styles as well ([docs](https://swagger.io/docs/specification/serialization/#path)) automatically. - -### Request - -The `GET()` request shown needed the `params` object that groups [parameters by type](https://spec.openapis.org/oas/latest.html#parameter-object) (`path` or `query`). If a required param is missing, or the wrong type, a type error will be thrown. - -The `POST()` request required a `body` object that provided all necessary [requestBody](https://spec.openapis.org/oas/latest.html#request-body-object) data. - -### Response - -All methods return an object with **data**, **error**, and **response**. - -```ts -const { data, error, response } = await client.GET("/url"); -``` - -| Object | Response | -| :--------- | :-------------------------------------------------------------------------------------------------------------------------- | -| `data` | `2xx` response if OK; otherwise `undefined` | -| `error` | `5xx`, `4xx`, or `default` response if not OK; otherwise `undefined` | -| `response` | [The original Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) which contains `status`, `headers`, etc. | - -## Support +## 📓 Docs -| Platform | Support | -| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Browsers** | [See fetch API support](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API#browser_compatibility) (widely-available in all major browsers) | -| **Node** | >= 18.0.0 | -| **TypeScript** | >= 4.7 (>= 5.0 recommended) | +[View Docs](https://openapi-ts.dev/openapi-fetch/) \ No newline at end of file diff --git a/packages/openapi-typescript/README.md b/packages/openapi-typescript/README.md index bcb40edf7..e6b65bd11 100644 --- a/packages/openapi-typescript/README.md +++ b/packages/openapi-typescript/README.md @@ -2,7 +2,7 @@ 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. +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. @@ -18,7 +18,7 @@ _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/) +👀 [See examples](./examples/) ## Setup @@ -30,7 +30,7 @@ npm i -D openapi-typescript typescript And in your `tsconfig.json`, to load the types properly: -```diff [tsconfig.json] +```diff { "compilerOptions": { + "module": "ESNext", // or "NodeNext" @@ -39,11 +39,10 @@ And in your `tsconfig.json`, to load the types properly: } ``` -> **Tip:** > **Highly recommended** > > Also adding the following can boost type safety: -> ```diff [tsconfig.json] +> ```diff > { > "compilerOptions": { > + "noUncheckedIndexedAccess": true @@ -67,7 +66,7 @@ npx openapi-typescript https://myapi.dev/api/v1/openapi.yaml -o ./path/to/my/sch Then in your TypeScript project, import types where needed: -```ts [src/my-project.ts] +```ts import type { paths, components } from "./my-openapi-3-schema"; // generated by openapi-typescript // Schema Obj @@ -85,8 +84,12 @@ type ErrorResponse = 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/)) +- 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/)