Skip to content

Commit d869503

Browse files
radist2sradist2s
committed
docs: add versioned docs for 2.14.0
1 parent 3e2b563 commit d869503

65 files changed

Lines changed: 6087 additions & 3 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎website/docusaurus.config.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,9 @@ const config = {
5353
current: {
5454
label: '2.x',
5555
},
56+
'2.14.0': {
57+
label: '2.14.0',
58+
},
5659
'1.x': {
5760
label: '1.x',
5861
},

‎website/versioned_docs/version-2.14.0/authorization/_category_.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"label": "Authentication \uD83E\uDDEA",
3+
"position": 45,
4+
"collapsible": true,
5+
"collapsed": true,
6+
"link": null
7+
}

‎website/versioned_docs/version-2.14.0/authorization/api-key-authentication.mdx‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
sidebar_position: 25
3+
---
4+
5+
# API Key Authentication
6+
7+
The `SecuritySchemeAPIKey` type is used for API key authentication, where the key can be placed in different locations
8+
such as headers or query parameters.
9+
10+
See the [OpenAPI API Key Authentication 🔗](https://swagger.io/docs/specification/authentication/api-keys/) specification for more information.
11+
12+
```ts
13+
type SecuritySchemeAPIKey = {
14+
/** Where the secret should be placed. */
15+
in: 'header' | 'query';
16+
/** Name of the secret key. */
17+
name: string;
18+
/** Secret to be used for authentication. */
19+
value: string;
20+
/** Refresh interval in milliseconds. */
21+
refreshInterval?: number;
22+
};
23+
```
24+
25+
- **Location**: Specifies that the secret is placed in the header or query parameters.
26+
- **Name**: The name of the secret key.
27+
- **Value**: The secret key to be used for authentication.
28+
- **Refresh Interval**: (Optional) The interval (in milliseconds) at which the key should be refreshed.
29+
30+
### Example
31+
32+
```tsx
33+
import { QraftSecureRequestFn } from '@openapi-qraft/react/Unstable_QraftSecureRequestFn';
34+
import { requestFn } from '@openapi-qraft/react';
35+
import { createAPIClient } from './api'; // generated by OpenAPI Qraft CLI
36+
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
37+
38+
import { useMemo, createContext, type ReactNode } from 'react';
39+
40+
const App = ({ children }: { children: ReactNode }) => {
41+
const queryClient = useMemo(() => new QueryClient(), []);
42+
43+
return (
44+
<QueryClientProvider client={queryClient}>
45+
<QraftSecureRequestFn
46+
requestFn={requestFn}
47+
securitySchemes={{
48+
apiClientSecret: async () => {
49+
const api = createAPIClient({
50+
requestFn,
51+
baseUrl: 'https://petstore3.swagger.io/api/v3',
52+
});
53+
54+
const { secret } = await api.auth.getAPISecret({ parameters: undefined }, requestFn);
55+
return {
56+
in: 'header', // specify the location of the secret, either 'header' or 'query'
57+
name: 'X-API-Secret',
58+
value: secret,
59+
// Specify the refresh interval in milliseconds if needed, or use Infinity to ask for the secret just once
60+
refreshInterval: Infinity,
61+
};
62+
}
63+
}}
64+
>
65+
{(secureRequestFn) => {
66+
// When using `secureRequestFn`, all requests that require the `apiClientSecret` security scheme
67+
// will automatically include the `X-API-Secret: <secret>` header.
68+
// This ensures that these requests are authenticated using the API Key Authentication mechanism.
69+
const api = createAPIClient({
70+
queryClient,
71+
requestFn: secureRequestFn,
72+
baseUrl: 'https://petstore3.swagger.io/api/v3',
73+
});
74+
75+
return (
76+
<MyAPIContext.Provider value={api}>
77+
{children}
78+
</MyAPIContext.Provider>
79+
)
80+
}}
81+
</QraftSecureRequestFn>
82+
</QueryClientProvider>
83+
);
84+
};
85+
86+
const MyAPIContext = createContext<ReturnType<typeof createAPIClient>>(null!);
87+
88+
export default App;
89+
```

‎website/versioned_docs/version-2.14.0/authorization/basic-authentication.mdx‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
sidebar_position: 30
3+
---
4+
5+
# Basic Authentication
6+
7+
The `SecuritySchemeBasic` type is used for basic authentication, where credentials are required.
8+
9+
See the [OpenAPI Basic Authentication 🔗](https://swagger.io/docs/specification/authentication/basic-authentication/) specification for more information.
10+
11+
```ts
12+
type SecuritySchemeBasic = {
13+
/** Credentials to be used for authentication. */
14+
credentials: string;
15+
16+
/** Refresh interval in milliseconds. */
17+
refreshInterval: number;
18+
}
19+
```
20+
21+
- **Credentials**: A string representing the username and password encoded in Base64.
22+
- **Refresh Interval**: The interval (in milliseconds) at which the key should be refreshed.
23+
24+
### Example
25+
26+
```tsx
27+
import { QraftSecureRequestFn } from '@openapi-qraft/react/Unstable_QraftSecureRequestFn';
28+
import { requestFn } from '@openapi-qraft/react';
29+
import { createAPIClient } from './api'; // generated by OpenAPI Qraft CLI
30+
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
31+
32+
import { useMemo, createContext, type ReactNode } from 'react';
33+
34+
const App = ({ children }: { children: ReactNode }) => {
35+
const queryClient = useMemo(() => new QueryClient(), []);
36+
37+
return (
38+
<QueryClientProvider client={queryClient}>
39+
<QraftSecureRequestFn
40+
requestFn={requestFn}
41+
securitySchemes={{
42+
basicAuth: () => {
43+
// Function to prompt user for basic authentication credentials
44+
const username = prompt('Enter your username:');
45+
const password = prompt('Enter your password:');
46+
return {
47+
credentials: btoa(`${username}:${password}`),
48+
// Ask for credentials just once or specify the refresh interval in milliseconds.
49+
refreshInterval: Infinity,
50+
};
51+
}
52+
}}
53+
>
54+
{(secureRequestFn) => {
55+
const api = createAPIClient({
56+
queryClient,
57+
requestFn: secureRequestFn,
58+
baseUrl: 'https://petstore3.swagger.io/api/v3',
59+
});
60+
61+
// When using `secureRequestFn`, the first request that requires the `basicAuth` security scheme
62+
// will prompt the user for their username and password. These credentials are then encoded in
63+
// Base64 format and included in the `Authorization: Basic <credentials>` header for subsequent requests.
64+
// This ensures that the requests are authenticated using Basic Authentication.
65+
// The credentials will be asked just once, and all following requests will reuse the entered credentials.
66+
return (
67+
<MyAPIContext.Provider value={api}>
68+
{children}
69+
</MyAPIContext.Provider>
70+
)
71+
}}
72+
</QraftSecureRequestFn>
73+
</QueryClientProvider>
74+
);
75+
};
76+
77+
const MyAPIContext = createContext<ReturnType<typeof createAPIClient>>(null!);
78+
79+
export default App;
80+
```

‎website/versioned_docs/version-2.14.0/authorization/bearer-authentication.mdx‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
sidebar_position: 20
3+
sidebar_label: Bearer Authentication
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
# Bearer Token Authentication
10+
11+
The `SecuritySchemeBearer` type supports bearer token authentication, commonly used with JWT tokens. It can either be
12+
a simple `string` representing the JWT token or an object with additional metadata if another token format is used.
13+
14+
See the [OpenAPI Bearer Authentication 🔗](https://swagger.io/docs/specification/authentication/bearer-authentication/) specification for more information.
15+
16+
```ts
17+
type SecuritySchemeBearer =
18+
| string /** JWT Bearer token **/
19+
| {
20+
/** Refresh interval in milliseconds. */
21+
refreshInterval: number;
22+
/** Token to be used for authentication. */
23+
token: string;
24+
};
25+
```
26+
27+
- **String**: A simple JWT Bearer token string.
28+
- The JWT must include the `exp` (expiration time) and `iat` (issued at) fields.
29+
- `QraftSecureRequestFn` will automatically refresh the token if it expires.
30+
- If the `exp` and `iat` fields are not present, an object token format must be used; otherwise, an error will be thrown.
31+
- **Object**: An object containing:
32+
- `refreshInterval`: The interval (in milliseconds) at which the token should be refreshed.
33+
- `token`: The JWT token to be used for authentication.
34+
35+
### Examples
36+
37+
<Tabs>
38+
<TabItem value="jwt-bearer" label="JWT Bearer" default>
39+
When providing a simple JWT Bearer token string, the token will be used as is. `QraftSecureRequestFn` will refresh
40+
the token if it expires based on the `exp` (expiration time) and `iat` (issued at) fields.
41+
42+
In this example, the `clientToken` security scheme handler is used to obtain and refresh the JWT Bearer token:
43+
44+
```tsx
45+
import { QraftSecureRequestFn } from '@openapi-qraft/react/Unstable_QraftSecureRequestFn';
46+
import { requestFn } from '@openapi-qraft/react';
47+
import { createAPIClient } from './api'; // generated by OpenAPI Qraft CLI
48+
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
49+
50+
import { useMemo, createContext, type ReactNode } from 'react';
51+
52+
const App = ({ children }: { children: ReactNode }) => {
53+
const queryClient = useMemo(() => new QueryClient(), []);
54+
55+
return (
56+
<QueryClientProvider client={queryClient}>
57+
<QraftSecureRequestFn
58+
requestFn={requestFn}
59+
securitySchemes={{
60+
clientToken: async ({ isRefreshing }) => {
61+
const api = createAPIClient({
62+
requestFn,
63+
baseUrl: 'https://petstore3.swagger.io/api/v3',
64+
});
65+
66+
if (!isRefreshing) {
67+
const { access_token } = await api.auth.obtainToken({
68+
body: {
69+
grant_type: 'client_credentials', // specify `body` or `parameters` if needed
70+
},
71+
});
72+
73+
// If token is JWT Bearer, return the token string
74+
// The token will be used in the `Authorization: Bearer <token>` header
75+
return access_token;
76+
}
77+
78+
const { access_token } = await api.auth.refreshToken({
79+
body: {
80+
grant_type: 'client_credentials', // specify `body` or `parameters` if needed
81+
},
82+
});
83+
84+
return access_token;
85+
}
86+
}}
87+
>
88+
{(secureRequestFn) => {
89+
// When using `secureRequestFn`, all requests that require the `clientToken` security scheme
90+
// will automatically include the `Authorization: Bearer <token>` header.
91+
// This ensures that these requests are authenticated with the provided JWT token.
92+
const api = createAPIClient({
93+
queryClient,
94+
requestFn: secureRequestFn,
95+
baseUrl: 'https://petstore3.swagger.io/api/v3',
96+
});
97+
98+
return (
99+
<MyAPIContext.Provider value={api}>
100+
{children}
101+
</MyAPIContext.Provider>
102+
)
103+
}}
104+
</QraftSecureRequestFn>
105+
</QueryClientProvider>
106+
);
107+
};
108+
109+
const MyAPIContext = createContext<ReturnType<typeof createAPIClient>>(null!);
110+
111+
export default App;
112+
```
113+
</TabItem>
114+
<TabItem value="custom-token" label="Custom Token">
115+
In case the token format is different from the standard JWT Bearer token, you can provide an object with
116+
`refreshInterval` and `token` properties.
117+
118+
```tsx
119+
import { QraftSecureRequestFn } from '@openapi-qraft/react/Unstable_QraftSecureRequestFn';
120+
import { requestFn } from '@openapi-qraft/react';
121+
import { createAPIClient } from './api'; // generated by OpenAPI Qraft CLI
122+
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
123+
124+
import { useMemo, createContext, type ReactNode } from 'react';
125+
126+
const App = ({ children }: { children: ReactNode }) => {
127+
const queryClient = useMemo(() => new QueryClient(), []);
128+
129+
return (
130+
<QueryClientProvider client={queryClient}>
131+
<QraftSecureRequestFn
132+
requestFn={requestFn}
133+
securitySchemes={{
134+
clientToken: async ({ isRefreshing }) => {
135+
const api = createAPIClient({
136+
queryClient,
137+
requestFn,
138+
baseUrl: 'https://petstore3.swagger.io/api/v3',
139+
});
140+
141+
if (!isRefreshing) {
142+
// Use Qraft's built-in Vanilla operation methods to fetch the token
143+
const { access_token, expires_in } = await api.auth.obtainToken({
144+
body: {
145+
grant_type: 'client_credentials', // specify `body` or `parameters` if needed
146+
},
147+
}, requestFn);
148+
149+
return {
150+
refreshInterval: expires_in * 1000, // specify the refresh interval in milliseconds
151+
token: access_token, // specify the token to be used in the `Authorization: Bearer <token>` header
152+
};
153+
}
154+
155+
const { access_token, expires_in } = await api.auth.refreshToken({
156+
body: {
157+
grant_type: 'client_credentials',
158+
},
159+
}, requestFn);
160+
161+
return {
162+
refreshInterval: expires_in * 1000,
163+
token: access_token,
164+
};
165+
}
166+
}}
167+
>
168+
{(secureRequestFn) => {
169+
// When using `secureRequestFn`, all requests that require the `clientToken` security scheme
170+
// will automatically include the `Authorization: Bearer <token>` header.
171+
// This ensures that these requests are authenticated with the provided JWT token.
172+
const api = createAPIClient({
173+
queryClient,
174+
requestFn: secureRequestFn,
175+
baseUrl: 'https://petstore3.swagger.io/api/v3',
176+
});
177+
178+
return (
179+
<MyAPIContext.Provider value={api}>
180+
{children}
181+
</MyAPIContext.Provider>
182+
)
183+
}}
184+
</QraftSecureRequestFn>
185+
</QueryClientProvider>
186+
);
187+
};
188+
189+
const MyAPIContext = createContext<ReturnType<typeof createAPIClient>>(null!);
190+
191+
export default App;
192+
```
193+
</TabItem>
194+
</Tabs>

0 commit comments

Comments
 (0)