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/about.md
+14-3
Original file line number
Diff line number
Diff line change
@@ -18,17 +18,28 @@ description: openapi-fetch Project Goals, comparisons, and more
18
18
19
19
## Differences
20
20
21
+
### vs. Axios
22
+
23
+
[Axios](https://axios-http.com) doesn’t automatically typecheck against your OpenAPI schema. Further, there’s no easy way to do that. Axios does have more features than openapi-fetch such as request/responce interception and cancellation.
24
+
25
+
### vs. tRPC
26
+
27
+
[tRPC](https://trpc.io/) is meant for projects where both the backend and frontend are written in TypeScript (Node.js). openapi-fetch is universal, and can work with any backend that follows an OpenAPI 3.x schema.
28
+
21
29
### vs. openapi-typescript-fetch
22
30
23
-
This library is identical in purpose to [openapi-typescript-fetch](https://github.com/ajaishankar/openapi-typescript-fetch), but has the following differences:
31
+
[openapi-typescript-fetch](https://github.com/ajaishankar/openapi-typescript-fetch) predates openapi-fetch, and is nearly identical in purpos, but differs mostly in syntax (so it’s more of an opinionated choice):
24
32
25
33
- This library has a built-in `error` type for `3xx`/`4xx`/`5xx` errors whereas openapi-typescript-fetch throws exceptions (requiring you to wrap things in `try/catch`)
26
34
- This library has a more terse syntax (`get(…)`) wheras openapi-typescript-fetch requires chaining (`.path(…).method(…).create()`)
27
-
- openapi-typescript-fetch supports middleware whereas this library doesn’t
28
35
29
36
### vs. openapi-typescript-codegen
30
37
31
-
This library is quite different from [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen)
38
+
[openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) is a codegen library, which is fundamentally different from openapi-fetch’s “no codegen” approach. openapi-fetch uses static TypeScript typechecking that all happens at build time with no client weight and no performance hit to runtime. Traditional codegen generates hundreds (if not thousands) of different functions that all take up client weight and slow down runtime.
39
+
40
+
### vs. Swagger Codegen
41
+
42
+
Swagger Codegen is the original codegen project for Swagger/OpenAPI, and has the same problems of other codgen approaches of size bloat and runtime performance problems. Further, Swagger Codegen require the Java runtime to work, whereas openapi-typescript/openapi-fetch don’t as native Node.js projects.
Copy file name to clipboardExpand all lines: docs/openapi-fetch/api.md
+98
Original file line number
Diff line number
Diff line change
@@ -37,6 +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:
95
+
96
+
```ts
97
+
createClient({
98
+
middleware: [
99
+
asyncfunction myMiddleware({
100
+
req, // request (undefined for responses)
101
+
res, // response (undefined for requests)
102
+
options, // all options passed to openapi-fetch
103
+
}) {
104
+
if (req) {
105
+
returnnewRequest(req.url, {
106
+
...req,
107
+
headers: { ...req.headers, foo: "bar" },
108
+
});
109
+
} elseif (res) {
110
+
returnnewResponse({
111
+
...res,
112
+
status: 200,
113
+
});
114
+
}
115
+
},
116
+
],
117
+
});
118
+
```
119
+
120
+
### Request pass
121
+
122
+
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
130
+
131
+
The response pass returns a standard [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance with no modifications.
132
+
133
+
### Skipping middleware
134
+
135
+
If you want to skip the middleware under certain conditions, just `return` as early as possible:
136
+
137
+
```ts
138
+
asyncfunction myMiddleware({ req }) {
139
+
if (req.schemaPath!=="/projects/{project_id}") {
140
+
return;
141
+
}
142
+
143
+
// …
144
+
}
145
+
```
146
+
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.
148
+
149
+
### Handling statefulness
150
+
151
+
When using middleware, it’s important to remember 2 things:
152
+
153
+
-**Create new instances** when modifying (e.g. `new Response()`)
154
+
-**Clone bodies** before accessing (e.g. `res.clone().json()`)
155
+
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).
0 commit comments