Skip to content

Commit 119260b

Browse files
drwpowdrwpow
committed
Update docs
1 parent 73d512c commit 119260b

File tree

4 files changed

+134
-70
lines changed

4 files changed

+134
-70
lines changed

‎docs/openapi-fetch/api.md

+60-44
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,19 @@ description: openapi-fetch API
55

66
# API
77

8-
## Create Client
8+
## createClient
99

1010
**createClient** accepts the following options, which set the default settings for all subsequent fetch calls.
1111

1212
```ts
1313
createClient<paths>(options);
1414
```
1515

16-
| Name | Type | Description |
17-
| :---------------- | :-------------: | :-------------------------------------------------------------------------------------------------------------------------------------- |
18-
| `baseUrl` | `string` | Prefix all fetch URLs with this option (e.g. `"https://myapi.dev/v1/"`) |
19-
| `fetch` | `fetch` | Fetch instance used for requests (default: `globalThis.fetch`) |
16+
| Name | Type | Description |
17+
| :---------------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
18+
| `baseUrl` | `string` | Prefix all fetch URLs with this option (e.g. `"https://myapi.dev/v1/"`) |
19+
| `fetch` | `fetch` | Fetch instance used for requests (default: `globalThis.fetch`) |
2020
| `querySerializer` | QuerySerializer | (optional) Provide a [querySerializer](#queryserializer) |
21-
| `pathSerializer` | PathSerializer | (optional) Provide a [pathSerializer](#pathserializer) |
2221
| `bodySerializer` | BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer) |
2322
| (Fetch options) | | Any valid fetch option (`headers`, `mode`, `cache`, `signal` …) ([docs](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options) |
2423

@@ -30,22 +29,23 @@ The following options apply to all request methods (`.GET()`, `.POST()`, etc.)
3029
client.get("/my-url", options);
3130
```
3231

33-
| Name | Type | Description |
34-
| :---------------- | :---------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35-
| `params` | ParamsObject | [path](https://swagger.io/specification/#parameter-locations) and [query](https://swagger.io/specification/#parameter-locations) params for the endpoint |
36-
| `body` | `{ [name]:value }` | [requestBody](https://spec.openapis.org/oas/latest.html#request-body-object) data for the endpoint |
37-
| `querySerializer` | QuerySerializer | (optional) Provide a [querySerializer](#queryserializer) |
38-
| `pathSerializer` | PathSerializer | (optional) Provide a [pathSerializer](#pathserializer) |
39-
| `bodySerializer` | BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer) |
32+
| Name | Type | Description |
33+
| :---------------- | :---------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34+
| `params` | ParamsObject | [path](https://swagger.io/specification/#parameter-locations) and [query](https://swagger.io/specification/#parameter-locations) params for the endpoint |
35+
| `body` | `{ [name]:value }` | [requestBody](https://spec.openapis.org/oas/latest.html#request-body-object) data for the endpoint |
36+
| `querySerializer` | QuerySerializer | (optional) Provide a [querySerializer](#queryserializer) |
37+
| `bodySerializer` | BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer) |
4038
| `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. |
41-
| `fetch` | `fetch` | Fetch instance used for requests (default: fetch from `createClient`) |
39+
| `fetch` | `fetch` | Fetch instance used for requests (default: fetch from `createClient`) |
4240
| (Fetch options) | | Any valid fetch option (`headers`, `mode`, `cache`, `signal`, …) ([docs](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options)) |
4341

44-
### querySerializer
42+
## querySerializer
4543

46-
String, number, and boolean query params are straightforward when forming a request, but arrays and objects not so much. OpenAPI supports [different ways of handling each](https://swagger.io/docs/specification/serialization/#query). By default, this library serializes arrays using `style: "form", explode: true`, and objects using `style: "deepObject", explode: true`.
44+
OpenAPI supports [different ways of serializing objects and arrays](https://swagger.io/docs/specification/serialization/#query) for parameters (strings, numbers, and booleans—primitives—always behave the same way). By default, this library serializes arrays using `style: "form", explode: true`, and objects using `style: "deepObject", explode: true`, but you can customize that behavior with the `querySerializer` option (either on `createClient()` to control every request, or on individual requests for just one).
4745

48-
To change that behavior, you can supply `querySerializer` options that control how `object` and `arrays` are serialized for query params. This can either be passed on `createClient()` to control every request, or on individual requests for just one:
46+
### Object syntax
47+
48+
openapi-fetch ships the common serialization methods out-of-the-box:
4949

5050
| Option | Type | Description |
5151
| :-------------- | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -68,9 +68,32 @@ const client = createClient({
6868
});
6969
```
7070

71-
#### Function
71+
#### Array styles
72+
73+
| Style | Array `id = [3, 4, 5]` |
74+
| :--------------------------- | :---------------------- |
75+
| form | `/users?id=3,4,5` |
76+
| **form (exploded, default)** | `/users?id=3&id=4&id=5` |
77+
| spaceDelimited | `/users?id=3%204%205` |
78+
| spaceDelimited (exploded) | `/users?id=3&id=4&id=5` |
79+
| pipeDelimited | `/users?id=3\|4\|5` |
80+
| pipeDelimited (exploded) | `/users?id=3&id=4&id=5` |
81+
82+
#### Object styles
83+
84+
| Style | Object `id = {"role": "admin", "firstName": "Alex"}` |
85+
| :----------------------- | :--------------------------------------------------- |
86+
| form | `/users?id=role,admin,firstName,Alex` |
87+
| form (exploded) | `/users?role=admin&firstName=Alex` |
88+
| **deepObject (default)** | `/users?id[role]=admin&id[firstName]=Alex` |
89+
90+
> [!NOTE]
91+
>
92+
> **deepObject** is always exploded, so it doesn’t matter if you set `explode: true` or `explode: false`—it’ll generate the same output.
93+
94+
### Alternate function syntax
7295

73-
Sometimes your backend doesn’t use one of the standard serialization methods, in which case you can pass a function to `querySerializer` to serialize the entire string yourself with no restrictions:
96+
Sometimes your backend doesn’t use one of the standard serialization methods, in which case you can pass a function to `querySerializer` to serialize the entire string yourself. You’ll also need to use this if you’re handling deeply-nested objects and arrays in your params:
7497

7598
```ts
7699
const client = createClient({
@@ -91,33 +114,13 @@ const client = createClient({
91114
});
92115
```
93116

94-
::: warning
95-
96-
When serializing yourself, the string will be kept exactly as-authored, so you’ll have to call [encodeURI](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) or [encodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) to escape special characters.
97-
98-
:::
99-
100-
### pathSerializer
101-
102-
If your backend doesn’t use the standard `{param_name}` syntax, you can control the behavior of how path params are serialized according to the spec ([docs](https://swagger.io/docs/specification/serialization/#path)):
103-
104-
```ts
105-
const client = createClient({
106-
pathSerializer: {
107-
style: "label", // "simple" (default) | "label" | "matrix"
108-
},
109-
});
110-
```
111-
112-
::: info
117+
> [!WARNING]
118+
>
119+
> When serializing yourself, the string will be kept exactly as-authored, so you’ll have to call [encodeURI](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) or [encodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) to escape special characters.
113120
114-
The `explode` behavior ([docs](https://swagger.io/docs/specification/serialization/#path)) is determined automatically by the pathname, depending on whether an asterisk suffix is present or not, e.g. `/users/{id}` vs `/users/{id*}`. Globs are **NOT** supported, and the param name must still match exactly; the asterisk is only a suffix.
121+
## bodySerializer
115122

116-
:::
117-
118-
### bodySerializer
119-
120-
Similar to [querySerializer](#querySerializer), bodySerializer allows you to customize how the requestBody is serialized if you don’t want the default [JSON.stringify()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) behavior. You probably only need this when using `multipart/form-data`:
123+
Similar to [querySerializer](#queryserializer), bodySerializer allows you to customize how the requestBody is serialized if you don’t want the default [JSON.stringify()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) behavior. You probably only need this when using `multipart/form-data`:
121124

122125
```ts
123126
const { data, error } = await PUT("/submit", {
@@ -134,3 +137,16 @@ const { data, error } = await PUT("/submit", {
134137
},
135138
});
136139
```
140+
141+
## Path serialization
142+
143+
openapi-fetch supports path serialization as [outlined in the 3.1 spec](https://swagger.io/docs/specification/serialization/#path). This happens automatically, based on the specific format in your OpenAPI schema:
144+
145+
| Template | Style | Primitive `id = 5` | Array `id = [3, 4, 5]` | Object `id = {"role": "admin", "firstName": "Alex"}` |
146+
| :---------------- | :------------------- | :----------------- | :----------------------- | :--------------------------------------------------- |
147+
| **`/users/{id}`** | **simple (default)** | **`/users/5`** | **`/users/3,4,5`** | **`/users/role,admin,firstName,Alex`** |
148+
| `/users/{id*}` | simple (exploded) | `/users/5` | `/users/3,4,5` | `/users/role=admin,firstName=Alex` |
149+
| `/users/{.id}` | label | `/users/.5` | `/users/.3,4,5` | `/users/.role,admin,firstName,Alex` |
150+
| `/users/{.id*}` | label (exploded) | `/users/.5` | `/users/.3.4.5` | `/users/.role=admin.firstName=Alex` |
151+
| `/users/{;id}` | matrix | `/users/;id=5` | `/users/;id=3,4,5` | `/users/;id=role,admin,firstName,Alex` |
152+
| `/users/{;id*}` | matrix (exploded) | `/users/;id=5` | `/users/;id=3;id=4;id=5` | `/users/;role=admin;firstName=Alex` |

‎docs/openapi-fetch/examples.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -130,4 +130,8 @@ _Note: if you’re using Svelte without SvelteKit, the root example in `src/rout
130130

131131
### Vue
132132

133-
TODO
133+
There isn’t an example app in Vue yet. Are you using it in Vue? Please [open a PR to add it!](https://github.com/drwpow/openapi-typescript/pulls)
134+
135+
---
136+
137+
Additional examples are always welcome! Please [open a PR](https://github.com/drwpow/openapi-typescript/pulls) with your examples.

‎docs/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,6 @@
1010
"update-contributors": "node scripts/update-contributors.js"
1111
},
1212
"devDependencies": {
13-
"vitepress": "1.0.0-rc.40"
13+
"vitepress": "1.0.0-rc.42"
1414
}
1515
}

0 commit comments

Comments
 (0)