docs: Document consistency

phk422 · phk422 · commit 7f76e4b679b4 · 2024-07-09T11:21:15.000+08:00
diff --git a/packages/openapi-fetch/README.md b/packages/openapi-fetch/README.md
@@ -1,6 +1,6 @@
 <img src="../../docs/public/assets/openapi-fetch.svg" alt="openapi-fetch" width="216" height="40" />
 
-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,28 +49,29 @@ 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:
 
 ```bash
 npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts
 ```
 
-> ⚠️ 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.
-
-Lastly, be sure to **run typechecking** in your project. This can be done by adding `tsc --noEmit` to your <a href="https://docs.npmjs.com/cli/v9/using-npm/scripts" target="_blank" rel="noopener noreferrer">npm scripts</a> 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)                                                                                                                        |
