@kubb/plugin-axios 6.0.3 → 6.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +2 -2
- package/dist/index.js +2 -2
- package/docs/guides/calling-operations.md +45 -80
- package/docs/guides/configure-requests.md +206 -0
- package/docs/guides/error-handling.md +73 -81
- package/docs/guides/migrate-to-v6.md +147 -202
- package/docs/guides/serialization.md +135 -91
- package/docs/guides/server-sent-events.md +136 -276
- package/docs/guides/transport.md +53 -30
- package/docs/options.md +72 -85
- package/docs/overview.md +33 -15
- package/kubb-extension.json +1 -1
- package/package.json +2 -2
- package/docs/guides/authentication.md +0 -101
- package/docs/guides/base-url.md +0 -102
- package/docs/guides/interceptors.md +0 -109
|
@@ -1,115 +1,120 @@
|
|
|
1
1
|
# Configure serialization
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Change how the generated client encodes parameters by their OpenAPI `style` and `explode`, and how it encodes and decodes bodies by media type.
|
|
4
|
+
|
|
5
|
+
Each generated call carries its parameter styles and content types, so most specs need no setup.
|
|
4
6
|
|
|
5
7
|
## Parameter styles
|
|
6
8
|
|
|
7
|
-
A parameter without `style` or `explode` in the spec uses
|
|
9
|
+
A parameter without `style` or `explode` in the spec uses its location's default.
|
|
10
|
+
|
|
11
|
+
::tabs
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
:::tabs-item{label="Query"}
|
|
10
14
|
|
|
11
|
-
|
|
12
|
-
says otherwise, and `spaceDelimited`, `pipeDelimited`, and `deepObject` change how arrays and
|
|
13
|
-
objects collapse.
|
|
15
|
+
For a query parameter named `id`:
|
|
14
16
|
|
|
15
|
-
| Style | `explode` | Input
|
|
16
|
-
| ---------------- | --------- |
|
|
17
|
-
| `form` (default) | `true` | `
|
|
18
|
-
| `form` | `false` | `
|
|
19
|
-
| `
|
|
20
|
-
| `
|
|
21
|
-
| `
|
|
17
|
+
| Style | `explode` | Input | Sent |
|
|
18
|
+
| ---------------- | --------- | ---------------- | ---------------- |
|
|
19
|
+
| `form` (default) | `true` | `[3, 4, 5]` | `id=3&id=4&id=5` |
|
|
20
|
+
| `form` | `false` | `[3, 4, 5]` | `id=3,4,5` |
|
|
21
|
+
| `form` (default) | `true` | `{ a: 1, b: 2 }` | `a=1&b=2` |
|
|
22
|
+
| `spaceDelimited` | `false` | `[3, 4, 5]` | `id=3%204%205` |
|
|
23
|
+
| `pipeDelimited` | `false` | `[3, 4, 5]` | `id=3%7C4%7C5` |
|
|
24
|
+
| `deepObject` | n/a | `{ a: 1 }` | `id%5Ba%5D=1` |
|
|
22
25
|
|
|
23
|
-
|
|
24
|
-
so the delimiter only shows with `explode: false`.
|
|
26
|
+
`spaceDelimited` and `pipeDelimited` default `explode` to `false`. A space in a value goes out as `%20`.
|
|
25
27
|
|
|
26
|
-
|
|
28
|
+
:::
|
|
27
29
|
|
|
28
|
-
Path
|
|
29
|
-
`.` and `matrix` prefixes a `;name=` segment. The results below are the serialized segment for a
|
|
30
|
-
parameter named `id`.
|
|
30
|
+
:::tabs-item{label="Path"}
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
For a path parameter named `id`, the segment that replaces `{id}`:
|
|
33
|
+
|
|
34
|
+
| Style | `explode` | Input | Sent |
|
|
33
35
|
| ------------------ | --------- | ---------------- | ----------------- |
|
|
34
36
|
| `simple` (default) | `false` | `[3, 4, 5]` | `3,4,5` |
|
|
37
|
+
| `simple` (default) | `false` | `{ x: 1, y: 2 }` | `x,1,y,2` |
|
|
35
38
|
| `label` | `true` | `[3, 4, 5]` | `.3.4.5` |
|
|
36
39
|
| `matrix` | `true` | `[3, 4, 5]` | `;id=3;id=4;id=5` |
|
|
37
|
-
| `simple` | `false` | `{ x: 1, y: 2 }` | `x,1,y,2` |
|
|
38
40
|
|
|
39
|
-
|
|
41
|
+
:::
|
|
42
|
+
|
|
43
|
+
:::tabs-item{label="Header"}
|
|
44
|
+
|
|
45
|
+
Headers always use the `simple` style. Only `explode` varies, and values are sent as they are.
|
|
46
|
+
|
|
47
|
+
| `explode` | Input | Sent |
|
|
48
|
+
| ----------------- | ------------------------------- | ---------------------- |
|
|
49
|
+
| `false` (default) | `'X-Ids': [3, 4]` | `X-Ids: 3,4` |
|
|
50
|
+
| `false` (default) | `'X-Filter': { role: 'admin' }` | `X-Filter: role,admin` |
|
|
51
|
+
| `true` | `'X-Filter': { role: 'admin' }` | `X-Filter: role=admin` |
|
|
52
|
+
|
|
53
|
+
:::
|
|
40
54
|
|
|
41
|
-
|
|
42
|
-
style and only let `explode` vary, so the metadata for these locations carries `explode` alone.
|
|
43
|
-
Header values are sent as-is, and cookie values are URL-encoded into a single `Cookie` header.
|
|
55
|
+
:::tabs-item{label="Cookie"}
|
|
44
56
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
|
|
|
57
|
+
Cookies use the `form` style, or the OpenAPI 3.2 `cookie` style, joined into one `Cookie` header.
|
|
58
|
+
|
|
59
|
+
| Style | `explode` | Input | Sent |
|
|
60
|
+
| ---------------- | --------- | --------------------------------- | ---------------------- |
|
|
61
|
+
| `form` (default) | `false` | `{ session: 'abc', ids: [1, 2] }` | `session=abc; ids=1,2` |
|
|
62
|
+
| `form` | `true` | `{ ids: [1, 2] }` | `ids=1; ids=2` |
|
|
63
|
+
| `cookie` | `true` | `{ ids: [1, 2] }` | `ids=1; ids=2` |
|
|
64
|
+
|
|
65
|
+
`form` percent-encodes values. `cookie` sends them as they are, and a value it cannot send, such as one with `;`, throws a `TypeError`.
|
|
66
|
+
|
|
67
|
+
:::
|
|
68
|
+
|
|
69
|
+
::
|
|
70
|
+
|
|
71
|
+
For `allowReserved` and `explode: true` on delimited styles, see [Delimited styles and allowReserved](#delimited-styles-and-allowreserved).
|
|
51
72
|
|
|
52
73
|
## Override parameter serialization
|
|
53
74
|
|
|
54
|
-
|
|
75
|
+
Set a `serializer` key on the client to replace that serializer for every call, or on one call. The keys are `query`, `path`, `header`, and `cookie`, and the other keys keep theirs:
|
|
55
76
|
|
|
56
77
|
```typescript
|
|
57
|
-
import { client } from './gen/.kubb/client'
|
|
58
78
|
import qs from 'qs'
|
|
79
|
+
import { client } from './gen/.kubb/client'
|
|
59
80
|
|
|
60
81
|
client.setConfig({
|
|
61
|
-
serializer: {
|
|
62
|
-
query: (params) => qs.stringify(params, { arrayFormat: 'brackets' }),
|
|
63
|
-
},
|
|
82
|
+
serializer: { query: (params) => qs.stringify(params, { arrayFormat: 'brackets' }) },
|
|
64
83
|
})
|
|
65
84
|
```
|
|
66
85
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
Kubb writes each serializer a spec needs into `.kubb/serializers/` and lists it in `.kubb/config.ts`, which `.kubb/client.ts` passes to `setConfig`. The core has no serializer of its own.
|
|
70
|
-
|
|
71
|
-
| Key in `serializer` | File | Written for |
|
|
72
|
-
| ------------------- | ------------------------------------------------------------------------------------ | ------------------------------ |
|
|
73
|
-
| `query` | `query.ts`, or `queryStyles.ts` for a spec with a styled query parameter | every spec |
|
|
74
|
-
| `path` | `path.ts`, plus `pathStyles.ts` for a spec with a `label` or `matrix` path parameter | every spec |
|
|
75
|
-
| `header` | `headers.ts` | a spec with a header parameter |
|
|
76
|
-
| `cookie` | `cookies.ts` | a spec with a cookie parameter |
|
|
77
|
-
|
|
78
|
-
A call that needs a serializer the spec did not register throws a `TypeError` that names the key, such as `serializer.cookie`. Set it on the client to send such a call. Without `serializer.header`, an array or object header value is sent as JSON.
|
|
86
|
+
Kubb writes only the serializers a spec needs. See [Serializer files](#serializer-files) for which files it writes.
|
|
79
87
|
|
|
80
88
|
## Built-in media types
|
|
81
89
|
|
|
82
90
|
| Keys | Encodes | Decodes |
|
|
83
91
|
| ---------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------ |
|
|
84
92
|
| `application/json`, `application/*+json`, `text/json` | JSON | JSON |
|
|
85
|
-
| `text/*` | a string
|
|
93
|
+
| `text/*` | a string as is | text |
|
|
86
94
|
| `multipart/form-data`, `application/x-www-form-urlencoded` | `FormData` or `URLSearchParams` from an object | `FormData` |
|
|
87
95
|
| `application/octet-stream`, `application/pdf`, `image/*`, `audio/*`, `video/*` | a `Blob` as is | `Blob` |
|
|
88
96
|
| `text/event-stream`, `application/jsonl`, `application/x-ndjson`, `application/json-seq` | | text, or item by item with `client.stream` |
|
|
89
97
|
| `*/*` | JSON for objects, strings and binary bodies as is | JSON, or text when the body is not JSON |
|
|
90
98
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
A key can be a pattern. The runtime lower-cases the type, drops its parameters, and tries the exact type, then a suffix such as `application/*+json`, then a wildcard such as `text/*`, then `*/*`. Write your own keys in lower case.
|
|
99
|
+
The runtime matches the lower-cased type without its parameters: the exact type, then a suffix such as `application/*+json`, then a wildcard such as `text/*`, then `*/*`. Write your own keys in lower case.
|
|
94
100
|
|
|
95
101
|
## Encode request bodies
|
|
96
102
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
Bodies that are already encoded (`FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, typed arrays, streams, and strings) pass through every built-in media type as they are. A string under a JSON media type is JSON-encoded.
|
|
103
|
+
For an operation with several request content types, set `contentType` on the call. A body without a content type goes out as `application/json`, unless it is already encoded.
|
|
100
104
|
|
|
101
|
-
|
|
102
|
-
|
|
105
|
+
- An encoded body passes every built-in media type as is: `FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, typed arrays, streams, and strings. Under a JSON media type, a string is JSON-encoded.
|
|
106
|
+
- For a `FormData` body, the runtime removes `Content-Type`, so the transport sets it with the multipart boundary.
|
|
107
|
+
- XML, YAML, and CSV have no built-in encoder, so an object under one throws a `TypeError`. Pass the encoded string, cast to the body type (`body: xml as unknown as AddPetBodyXml`), or add a media type.
|
|
103
108
|
|
|
104
|
-
|
|
109
|
+
For `bigint` bodies, see [`bigint` request bodies](#bigint-request-bodies).
|
|
105
110
|
|
|
106
111
|
## Add a media type
|
|
107
112
|
|
|
108
|
-
Register a handler under its media type
|
|
113
|
+
Register a handler under its media type in `mediaTypes`. `encode` gets the body and a context with the full `contentType`, and returns a body axios can send. `decode` gets the `Response`, so a binary format can read bytes:
|
|
109
114
|
|
|
110
115
|
```typescript
|
|
111
|
-
import { client } from './gen/.kubb/client'
|
|
112
116
|
import { XMLBuilder, XMLParser } from 'fast-xml-parser'
|
|
117
|
+
import { client } from './gen/.kubb/client'
|
|
113
118
|
|
|
114
119
|
client.setConfig({
|
|
115
120
|
mediaTypes: {
|
|
@@ -121,33 +126,27 @@ client.setConfig({
|
|
|
121
126
|
})
|
|
122
127
|
```
|
|
123
128
|
|
|
124
|
-
Handlers merge per key over the built-ins
|
|
125
|
-
|
|
126
|
-
A streaming format adds `stream`, which reads the 2xx body item by item. The runtime validates each item:
|
|
129
|
+
Handlers merge per key over the built-ins. For the merge order, see [Media type merge order](#media-type-merge-order). A streaming format adds `stream`, which reads a 2xx body item by item, and the runtime validates each item:
|
|
127
130
|
|
|
128
131
|
```typescript
|
|
129
132
|
client.setConfig({
|
|
130
|
-
mediaTypes: {
|
|
131
|
-
'multipart/mixed': { stream: (body, { contentType }) => readParts(body, boundaryOf(contentType)) },
|
|
132
|
-
},
|
|
133
|
+
mediaTypes: { 'multipart/mixed': { stream: (body, { contentType }) => readParts(body, boundaryOf(contentType)) } },
|
|
133
134
|
})
|
|
134
135
|
```
|
|
135
136
|
|
|
136
137
|
## Decode responses
|
|
137
138
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
- A 2xx response without a `Content-Type` is decoded as the media type the call asked for in `contentType.response`, then as `*/*`.
|
|
141
|
-
- A 204, 205, or 304 response, a `HEAD` request, and an empty body give `data: undefined`.
|
|
142
|
-
- Invalid JSON under a JSON media type throws a `ParseError`. Catch it, or register a lenient `application/json` handler.
|
|
139
|
+
Axios reads every body as bytes, then the runtime decodes it by the response `Content-Type`. Native axios response interceptors see those bytes, so use `client.interceptors.response` to see the decoded body. A `switch (result.contentType)` narrows `data` for an operation that returns several media types.
|
|
143
140
|
|
|
144
|
-
|
|
141
|
+
| Response | `data` |
|
|
142
|
+
| ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
143
|
+
| 204, 205, or 304, a `HEAD` request, or an empty body | `undefined` |
|
|
144
|
+
| Invalid JSON under a JSON media type | Throws a `ParseError`. Catch it, or register a lenient `application/json` handler. |
|
|
145
|
+
| 2xx with `parseAs` set on the call | Read as `'json'`, `'text'`, `'blob'`, `'arrayBuffer'`, or `'stream'`. |
|
|
145
146
|
|
|
146
|
-
|
|
147
|
-
const { data } = await getReport({ path: { id: '123' }, parseAs: 'text' })
|
|
148
|
-
```
|
|
147
|
+
For a 2xx without a `Content-Type`, see [Default content types](#default-content-types). For binary downloads and vendor types, see [Binary and vendor responses](#binary-and-vendor-responses).
|
|
149
148
|
|
|
150
|
-
|
|
149
|
+
XML, YAML, and CSV responses are typed `string`, even with an object schema. A media type you register changes the value but not the type, so cast `data`:
|
|
151
150
|
|
|
152
151
|
```typescript
|
|
153
152
|
const result = await getPetById({ path: { petId: 1 }, contentType: { response: 'application/xml' } })
|
|
@@ -156,27 +155,72 @@ if (result.contentType === 'application/xml') {
|
|
|
156
155
|
}
|
|
157
156
|
```
|
|
158
157
|
|
|
159
|
-
|
|
158
|
+
> [!NOTE]
|
|
159
|
+
> With the adapter's default [`integerType: 'bigint'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype), an `int64` field is typed `bigint`, but `JSON.parse` returns a `number`. Set `integerType: 'number'`, or turn on [`validator: 'zod'`](https://kubb.dev/extensions/kubb-labs/plugin-axios/options#validator), which converts the field. `JSON.parse` loses precision above `Number.MAX_SAFE_INTEGER` either way, so declare an exact 64-bit ID as a string.
|
|
160
160
|
|
|
161
|
-
[Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/server-sent-events) covers stream media types and `client.stream`.
|
|
161
|
+
Next, [Server-sent events](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/server-sent-events) covers the stream media types and `client.stream`.
|
|
162
162
|
|
|
163
|
-
|
|
164
|
-
> With the adapter's default [`integerType: 'bigint'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype), a `format: int64` field is typed `bigint`, but `JSON.parse` returns a `number`. Set `integerType: 'number'` on `adapterOas`, or turn on [`validator: 'zod'`](#validate-responses), which converts the field to `bigint`. Either way, `JSON.parse` loses precision above `Number.MAX_SAFE_INTEGER`, so declare an exact 64-bit ID as a string in the document.
|
|
163
|
+
## Less common cases
|
|
165
164
|
|
|
166
|
-
|
|
165
|
+
### Delimited styles and allowReserved
|
|
167
166
|
|
|
168
|
-
|
|
167
|
+
When a [query parameter](#parameter-styles) uses `spaceDelimited` or `pipeDelimited`, or sets `allowReserved`:
|
|
169
168
|
|
|
170
|
-
|
|
171
|
-
|
|
169
|
+
- `spaceDelimited` and `pipeDelimited` default `explode` to `false`. With `explode: true`, they repeat the key, like `form`.
|
|
170
|
+
- With `allowReserved`, reserved characters stay as they are, except `#`, `&`, and `+`.
|
|
172
171
|
|
|
173
|
-
|
|
174
|
-
```
|
|
172
|
+
### Serializer files
|
|
175
173
|
|
|
176
|
-
|
|
174
|
+
When you look for a serializer in `.kubb/serializers/`, Kubb writes only the ones the spec needs and registers them in `.kubb/config.ts`. Set a key from the table to replace one, as [Override parameter serialization](#override-parameter-serialization) shows.
|
|
177
175
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
176
|
+
| Key in `serializer` | File | Written for |
|
|
177
|
+
| ------------------- | -------------------------------------------------------------- | ------------------------------ |
|
|
178
|
+
| `query` | `query.ts`, or `queryStyles.ts` with a styled query parameter | every spec |
|
|
179
|
+
| `path` | `path.ts`, plus `pathStyles.ts` with a `label` or `matrix` one | every spec |
|
|
180
|
+
| `header` | `headers.ts` | a spec with a header parameter |
|
|
181
|
+
| `cookie` | `cookies.ts` | a spec with a cookie parameter |
|
|
182
|
+
|
|
183
|
+
A call that needs a serializer the spec did not register throws a `TypeError` that names it, such as `serializer.cookie`. Without `serializer.header`, an array or object header value goes out as JSON.
|
|
184
|
+
|
|
185
|
+
### Form and stream media types
|
|
186
|
+
|
|
187
|
+
When a form or stream type from [Built-in media types](#built-in-media-types) has no handler, the spec does not use it:
|
|
188
|
+
|
|
189
|
+
- `.kubb/config.ts` registers each form type only when the spec has a body of that type, from `.kubb/mediaTypes/formData.ts` and `.kubb/mediaTypes/urlencoded.ts`.
|
|
190
|
+
- It registers the stream types, `streamMediaTypes` from `.kubb/sse.ts`, only when the spec streams.
|
|
191
|
+
- `.kubb/client.ts` passes that config to `setConfig`.
|
|
192
|
+
|
|
193
|
+
To send a type the spec does not declare, register a handler, as [Add a media type](#add-a-media-type) shows.
|
|
194
|
+
|
|
195
|
+
### Default content types
|
|
196
|
+
|
|
197
|
+
When a call sets no `contentType`:
|
|
198
|
+
|
|
199
|
+
- An operation with one request content type has it built in. For one with several, set `contentType` on the call.
|
|
200
|
+
- A 2xx response without a `Content-Type` decodes as the call's `contentType.response`, then as `*/*`.
|
|
201
|
+
|
|
202
|
+
### `bigint` request bodies
|
|
203
|
+
|
|
204
|
+
When a request body holds a `bigint`, it goes out as a JSON number. A value outside the safe-integer range throws a `TypeError` instead of losing precision, so register a media type to send it another way.
|
|
205
|
+
|
|
206
|
+
### Media type merge order
|
|
207
|
+
|
|
208
|
+
When you register a handler for a type that already has one, handlers merge per key over the built-ins and over earlier `setConfig` calls. A handler passed on one call merges over the client's. An entry with only `decode` still encodes through the next match, such as `*/*`.
|
|
209
|
+
|
|
210
|
+
### Binary and vendor responses
|
|
211
|
+
|
|
212
|
+
When an operation's success content is only binary, Kubb sets `parseAs: 'blob'` on it, so `data` is a `Blob` whatever its media type. The generated types follow what the built-in media types return. A vendor type such as `application/vnd.github.object` keeps its schema type.
|
|
213
|
+
|
|
214
|
+
### Parameter validation
|
|
215
|
+
|
|
216
|
+
When [`validator`](https://kubb.dev/extensions/kubb-labs/plugin-axios/options#validator) checks `params`, the call sends what each `<operation>PathSchema`, `QuerySchema`, `HeadersSchema`, or `CookiesSchema` returns:
|
|
217
|
+
|
|
218
|
+
- A codec param such as a `Date` goes out in its wire form.
|
|
219
|
+
- Path and query keys the spec does not declare are stripped, such as a cache-buster.
|
|
220
|
+
- Undeclared headers pass through, and declared ones match in any casing. Client-level `headers` are checked too, and `auth` values are not.
|
|
221
|
+
|
|
222
|
+
With codecs, pair `request` and `params` with [`pluginZod({ inferred: 'codec' })`](https://kubb.dev/extensions/kubb-labs/plugin-zod/options#inferred), so the request types accept domain values such as a `Date`. To skip the checks, [turn validation off at runtime](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/error-handling#turn-validation-off-at-runtime).
|
|
223
|
+
|
|
224
|
+
### Error body validation
|
|
181
225
|
|
|
182
|
-
|
|
226
|
+
When `validator` is on and a non-2xx response has a body, the runtime checks it against the schema of its status, then its range such as `5xx`, then `default`. A status the document leaves out keeps its body unchecked. An error body that fails its schema throws a `ParseError` instead of the `ResponseError`, also with `throwOnError: false`. To recover, see [Validation failures](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/error-handling#validation-failures).
|