You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/openapi-fetch/api.md
+43-70
Original file line number
Diff line number
Diff line change
@@ -37,7 +37,7 @@ client.get("/my-url", options);
37
37
|`bodySerializer`| BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer)|
38
38
|`parseAs`|`"json"`\|`"text"`\|`"arrayBuffer"`\|`"blob"`\|`"stream"`| (optional) Parse the response using [a built-in instance method](https://developer.mozilla.org/en-US/docs/Web/API/Response#instance_methods) (default: `"json"`). `"stream"` skips parsing altogether and returns the raw stream. |
39
39
|`fetch`|`fetch`| Fetch instance used for requests (default: fetch from `createClient`) |
As of `0.9.0` this library supports lightweight middleware. Middleware allows you to modify either the request, response, or both for all fetches.
91
-
92
-
You can declare middleware as an array of functions on [createClient](#create-client). Each middleware function will be **called twice**—once for the request, then again for the response. On request, they’ll be called in array order. On response, they’ll be called in reverse-array order. That way the first middleware gets the first “dibs” on request, and the final control over responses.
93
-
94
-
Within your middleware function, you’ll either need to check for `req` (request) or `res` (response) to handle each pass appropriately:
90
+
Middleware is an object with `onRequest()` and `onResponse()` callbacks that can observe and modify requests and responses.
The request pass of each middleware provides `req` that’s a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) instance, but has 2 additional properties:
|`schemaPath`|`string`| The OpenAPI pathname called (e.g. `/projects/{project_id}`) |
127
-
|`params`|`Object`| The [params](#fetch-options) fetch option provided by the client |
128
-
129
-
### Response pass
113
+
::: tip
130
114
131
-
The response pass returns a standard [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance with no modifications.
115
+
Middleware can be a simple object. But wrapping in a function like the examples show lets you optionally create multiple instances of the same logic to handle different scenarios if needed.
132
116
133
-
### Skipping middleware
117
+
:::
134
118
135
-
If you want to skip the middleware under certain conditions, just `return` as early as possible:
119
+
### onRequest
136
120
137
121
```ts
138
-
asyncfunction myMiddleware({ req }) {
139
-
if (req.schemaPath!=="/projects/{project_id}") {
140
-
return;
141
-
}
142
-
122
+
onRequest(req, options) {
143
123
// …
144
124
}
145
125
```
146
126
147
-
This will leave the request/response unmodified, and pass things off to the next middleware handler (if any). There’s no internal callback or observer library needed.
|`req`|`MiddlewareRequest`| A standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) with `schemaPath` (OpenAPI pathname) and `params` ([params](/openapi-fetch/api#fetch-options) object) |
132
+
|`options`|`MergedOptiosn`| Combination of [createClient](/openapi-fetch/api#create-client) options + [fetch overrides](/openapi-fetch/api#fetch-options)|
150
133
151
-
When using middleware, it’s important to remember 2 things:
134
+
And it expects either:
152
135
153
-
-**Create new instances**when modifying (e.g. `new Response()`)
-**If modifying the request:**A [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request)
137
+
-**If not modifying:**`undefined` (void)
155
138
156
-
This is to account for the fact responses are [stateful](https://developer.mozilla.org/en-US/docs/Web/API/Response/bodyUsed), and if the stream is consumed in middleware [the client will throw an error](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone).
You can also use [proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) which are now supported in all modern browsers:
openapi-fetch is simple vanilla JS that can be used in any project. But sometimes the implementation in a framework may come with some prior art that helps you get the most out of your usage.
110
-
111
-
### React + React Query
9
+
## React + React Query
112
10
113
11
[React Query](https://tanstack.com/query/latest) is a perfect wrapper for openapi-fetch in React. At only 13 kB, it provides clientside caching and request deduping across async React components without too much client weight in return. And its type inference preserves openapi-fetch types perfectly with minimal setup.
114
12
115
13
[View a code example in GitHub](https://github.com/drwpow/openapi-typescript/tree/main/packages/openapi-fetch/examples/react-query)
116
14
117
-
###Next.js
15
+
## Next.js
118
16
119
17
[Next.js](https://nextjs.org/) is the most popular SSR framework for React. While [React Query](#react--react-query) is recommended for all clientside fetching with openapi-fetch (not SWR), this example shows how to take advantage of Next.js’s [server-side fetching](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#fetching-data-on-the-server-with-fetch) with built-in caching.
120
18
121
19
[View a code example in GitHub](https://github.com/drwpow/openapi-typescript/tree/main/packages/openapi-fetch/examples/nextjs)
122
20
123
-
###Svelte / SvelteKit
21
+
## Svelte / SvelteKit
124
22
125
23
[SvelteKit](https://kit.svelte.dev)’s automatic type inference can easily pick up openapi-fetch’s types in both clientside fetching and [Page Data](https://kit.svelte.dev/docs/load#page-data) fetching. And it doesn’t need any additional libraries to work. SvelteKit also advises to use their [custom fetch](https://kit.svelte.dev/docs/load#making-fetch-requests) in load functions. This can be achieved with [fetch options](/openapi-fetch/api#fetch-options).
126
24
127
25
_Note: if you’re using Svelte without SvelteKit, the root example in `src/routes/+page.svelte` doesn’t use any SvelteKit features and is generally-applicable to any setup._
128
26
129
27
[View a code example in GitHub](https://github.com/drwpow/openapi-typescript/tree/main/packages/openapi-fetch/examples/sveltekit)
Copy file name to clipboardExpand all lines: docs/openapi-fetch/index.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -94,7 +94,7 @@ And run `npm run test:ts` in your CI to catch type errors.
94
94
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.
95
95
:::
96
96
97
-
## Usage
97
+
## Basic Usage
98
98
99
99
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:
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 replace all `path` params for you (so they can be typechecked)
131
+
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).
0 commit comments