@kubb/plugin-axios 6.0.2 → 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 +3 -3
- package/docs/guides/authentication.md +0 -101
- package/docs/guides/base-url.md +0 -102
- package/docs/guides/interceptors.md +0 -109
package/docs/guides/base-url.md
DELETED
|
@@ -1,102 +0,0 @@
|
|
|
1
|
-
# Set the base URL
|
|
2
|
-
|
|
3
|
-
Set `baseURL` on the client plugin or on the generated client.
|
|
4
|
-
|
|
5
|
-
> [!NOTE]
|
|
6
|
-
> Top-level OpenAPI server URLs do not set the client's `baseURL`, even with the `server` option of `adapterOas`.
|
|
7
|
-
|
|
8
|
-
## Operations with their own server
|
|
9
|
-
|
|
10
|
-
A path or operation can declare its own `servers`, such as an upload or streaming host next to the main API. Its URL becomes that operation's default `baseURL`, so the call goes to that host. The `server.index` of `adapterOas` picks the entry, falling back to the first one.
|
|
11
|
-
|
|
12
|
-
```yaml [petStore.yaml]
|
|
13
|
-
paths:
|
|
14
|
-
/.sse:
|
|
15
|
-
servers:
|
|
16
|
-
- url: https://echo.websocket.org
|
|
17
|
-
get:
|
|
18
|
-
operationId: streamEvents
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
A relative server URL, such as `/v2`, or one with `{variable}` placeholders is skipped, so the client's `baseURL` applies.
|
|
22
|
-
|
|
23
|
-
## Pick a server by name
|
|
24
|
-
|
|
25
|
-
OpenAPI 3.2 lets a server have a `name`. The generated `.kubb/client.ts` exports the document's named servers as `servers`, so you can pick one by name:
|
|
26
|
-
|
|
27
|
-
```yaml [petStore.yaml]
|
|
28
|
-
servers:
|
|
29
|
-
- url: https://api.example.com
|
|
30
|
-
name: production
|
|
31
|
-
- url: https://staging.example.com
|
|
32
|
-
name: staging
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
```typescript
|
|
36
|
-
import { client, servers } from './gen/.kubb/client'
|
|
37
|
-
|
|
38
|
-
client.setConfig({ baseURL: servers.staging })
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
## Use the baseURL option
|
|
42
|
-
|
|
43
|
-
Pass `baseURL` to `pluginAxios` to set the generated default. Add `pluginTs` for the operation types.
|
|
44
|
-
|
|
45
|
-
```typescript [kubb.config.ts]
|
|
46
|
-
import { defineConfig } from 'kubb/config'
|
|
47
|
-
import { adapterOas } from '@kubb/adapter-oas'
|
|
48
|
-
import { pluginTs } from '@kubb/plugin-ts'
|
|
49
|
-
import { pluginAxios } from '@kubb/plugin-axios'
|
|
50
|
-
|
|
51
|
-
export default defineConfig({
|
|
52
|
-
input: './petStore.yaml',
|
|
53
|
-
output: { path: './src/gen' },
|
|
54
|
-
adapter: adapterOas({ integerType: 'number' }),
|
|
55
|
-
plugins: [
|
|
56
|
-
pluginTs(),
|
|
57
|
-
pluginAxios({ baseURL: 'https://localhost:8080/api/v1' }),
|
|
58
|
-
],
|
|
59
|
-
})
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
A value containing a `${...}` interpolation stays dynamic. The plugin emits it as a template literal in the generated client config, so `baseURL: '${process.env.API_URL}'` reads the environment variable when the app runs instead of baking in the build-time value.
|
|
63
|
-
|
|
64
|
-
## Set it at runtime
|
|
65
|
-
|
|
66
|
-
Use `client.setConfig` to configure all operations at startup:
|
|
67
|
-
|
|
68
|
-
```typescript
|
|
69
|
-
import { client } from './gen/.kubb/client'
|
|
70
|
-
|
|
71
|
-
client.setConfig({ baseURL: import.meta.env.VITE_API_URL })
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
Use `createClient` for an isolated client, then pass it to an operation:
|
|
75
|
-
|
|
76
|
-
```typescript
|
|
77
|
-
import { createClient } from './gen/.kubb/client'
|
|
78
|
-
import { getPetById } from './gen/clients/getPetById'
|
|
79
|
-
|
|
80
|
-
const staging = createClient({ baseURL: 'https://staging.petstore.swagger.io/v2' })
|
|
81
|
-
|
|
82
|
-
const { data } = await getPetById({ path: { petId: 1 }, client: staging })
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
Pass `baseURL` on a single call to override the client for that one request:
|
|
86
|
-
|
|
87
|
-
```typescript
|
|
88
|
-
import { getPetById } from './gen/clients/getPetById'
|
|
89
|
-
|
|
90
|
-
const { data } = await getPetById({ path: { petId: 1 }, baseURL: 'https://localhost:3000' })
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
## Which base URL a call uses
|
|
94
|
-
|
|
95
|
-
A call uses the first base URL it finds, in this order:
|
|
96
|
-
|
|
97
|
-
1. `baseURL` passed on the call.
|
|
98
|
-
2. The operation's own `servers`.
|
|
99
|
-
3. The path's `servers`.
|
|
100
|
-
4. The client passed as `client`, made with `createClient({ baseURL })`.
|
|
101
|
-
5. `client.setConfig({ baseURL })`.
|
|
102
|
-
6. The `baseURL` option of `pluginAxios`.
|
|
@@ -1,109 +0,0 @@
|
|
|
1
|
-
# Add interceptors
|
|
2
|
-
|
|
3
|
-
Register handlers on `client.interceptors.request`, `.response`, or `.error` to apply behavior across calls. Handlers receive the resolved request, the decoded result, or the error a call ends with.
|
|
4
|
-
|
|
5
|
-
## Run before the send
|
|
6
|
-
|
|
7
|
-
Request handlers run after URL construction, serialization, and authentication. Return the modified request:
|
|
8
|
-
|
|
9
|
-
```typescript
|
|
10
|
-
import { client } from './gen/.kubb/client'
|
|
11
|
-
|
|
12
|
-
client.interceptors.request.use((request) => {
|
|
13
|
-
request.headers['X-Request-ID'] = crypto.randomUUID()
|
|
14
|
-
return request
|
|
15
|
-
})
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
The handler receives a `ResolvedRequest` (`url`, `method`, `headers`, `body`, `signal`,
|
|
19
|
-
`credentials`, `options`, `stream`).
|
|
20
|
-
|
|
21
|
-
## Run after the send
|
|
22
|
-
|
|
23
|
-
Response handlers run after the body is decoded and before the status check and the validator, so a JSON body is
|
|
24
|
-
already parsed. On a `client.stream` call, `data` is the raw body stream. The handler receives a `DecodedResponse`
|
|
25
|
-
(`data`, `status`, `statusText`, `headers`, `contentType`, `request`, `response`):
|
|
26
|
-
|
|
27
|
-
```typescript
|
|
28
|
-
client.interceptors.response.use((result) => {
|
|
29
|
-
console.info(`${result.status} ${result.contentType}`)
|
|
30
|
-
return result
|
|
31
|
-
})
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
## React to an error
|
|
35
|
-
|
|
36
|
-
Error handlers get every failure: a `ResponseError` for a non-2xx status, a network error, an abort, or a
|
|
37
|
-
`ParseError`. Narrow with `ResponseError.is`:
|
|
38
|
-
|
|
39
|
-
```typescript
|
|
40
|
-
import { client, ResponseError } from './gen/.kubb/client'
|
|
41
|
-
|
|
42
|
-
client.interceptors.error.use((error) => {
|
|
43
|
-
if (ResponseError.is(error) && error.status === 401) scheduleTokenRefresh()
|
|
44
|
-
if (error.name === 'AbortError') console.info('canceled')
|
|
45
|
-
return error
|
|
46
|
-
})
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
Return another error, such as a domain error, and the call throws it instead. Each handler receives the error the one
|
|
50
|
-
before it returned. A handler that returns nothing keeps the error:
|
|
51
|
-
|
|
52
|
-
```typescript
|
|
53
|
-
class NotFoundError extends Error {}
|
|
54
|
-
|
|
55
|
-
client.interceptors.error.use((error) => (ResponseError.is(error) && error.status === 404 ? new NotFoundError(error.message) : error))
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
With `throwOnError: false`, a documented non-2xx response resolves and no error handler runs for it, so inspect the
|
|
59
|
-
returned `error` on the result. An error inside a stream loop throws from the loop and skips the error handlers.
|
|
60
|
-
|
|
61
|
-
## Add, replace, and remove handlers
|
|
62
|
-
|
|
63
|
-
`use` registers a handler and returns an id. Pass that id to `eject` to remove it, or to `update`
|
|
64
|
-
to swap its function in place.
|
|
65
|
-
|
|
66
|
-
> [!NOTE]
|
|
67
|
-
> Handlers run in the order you register them.
|
|
68
|
-
|
|
69
|
-
```typescript
|
|
70
|
-
const id = client.interceptors.request.use((request) => request)
|
|
71
|
-
|
|
72
|
-
client.interceptors.request.update(id, (request) => {
|
|
73
|
-
request.headers['X-Trace'] = 'on'
|
|
74
|
-
return request
|
|
75
|
-
})
|
|
76
|
-
|
|
77
|
-
client.interceptors.request.eject(id)
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
## Where to set them
|
|
81
|
-
|
|
82
|
-
Register handlers on the shared `client` for all operations. `client.createClient(config)` returns an instance with the
|
|
83
|
-
same config and no handlers. `client.extend(config)` returns one that runs the parent's handlers, even those added
|
|
84
|
-
later, before its own:
|
|
85
|
-
|
|
86
|
-
```typescript
|
|
87
|
-
import { client } from './gen/.kubb/client'
|
|
88
|
-
|
|
89
|
-
const admin = client.extend({ headers: { 'X-Role': 'admin' } })
|
|
90
|
-
admin.interceptors.request.use((request) => request) // runs after the handlers on client
|
|
91
|
-
await getPetById({ path: { petId: 1 }, client: admin })
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
The examples set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter, so an `int64` id such as `petId` is a `number`. With the default it is a `bigint` and the call takes `1n`.
|
|
95
|
-
|
|
96
|
-
## Native axios interceptors
|
|
97
|
-
|
|
98
|
-
To get the native `InternalAxiosRequestConfig`, `AxiosResponse`, or `AxiosError`, register an axios interceptor on `getAxiosInstance()`:
|
|
99
|
-
|
|
100
|
-
```typescript
|
|
101
|
-
import { getAxiosInstance } from './gen/.kubb/client'
|
|
102
|
-
|
|
103
|
-
getAxiosInstance().interceptors.request.use((config) => {
|
|
104
|
-
config.headers.set('traceparent', currentTraceparent())
|
|
105
|
-
return config
|
|
106
|
-
})
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
Native axios interceptors run after the `client.interceptors` request handlers, in reverse order of registration, and response interceptors see the raw bytes. An instance you wrap with `createAxiosTransport` keeps its own interceptors. See [Use a custom transport](https://kubb.dev/extensions/kubb-labs/plugin-axios/guides/transport).
|