fix(docs): Document inconsistency

Author: phk422

packages/openapi-typescript/README.md

@@ -1,53 +1,86 @@
 <img src="../../docs/public/assets/openapi-ts.svg" alt="openapi-typescript" width="200" height="40" />
 
-openapi-typescript generates TypeScript types from static <a href="https://spec.openapis.org/oas/latest.html" target="_blank" rel="noopener noreferrer">OpenAPI</a> 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 <a href="https://spec.openapis.org/oas/v3.1.0#discriminator-object" target="_blank" rel="noopener noreferrer">discriminators</a>)
-- ✅ 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 <a href="https://nodejs.org/en" target="_blank" rel="noopener noreferrer">Node.js</a> 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 <a href="https://redocly.com/docs/cli/commands/lint/" target="_blank" rel="noopener noreferrer">validate your schemas</a>! 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.)