Skip to content

Commit ba6be5a

Browse files
radist2sradist2s
authored
Merge pull request #442 from OpenAPI-Qraft/docs/add-missing-docs
docs: add missing docs
2 parents d6e256a + a3eb27e commit ba6be5a

27 files changed

Lines changed: 599 additions & 139 deletions

‎.github/actions/spelling/expect.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ radist
7575
reate
7676
redocly
7777
refetched
78-
Refetches
78+
refetches
7979
remarkjs
8080
remarkrc
8181
reqid
@@ -102,6 +102,7 @@ TMeta
102102
TMutation
103103
TOperation
104104
TPage
105+
TParameters
105106
TParams
106107
TQuery
107108
TRequest

‎website/docs/hooks/useInfiniteQuery.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,15 @@ const query = api.<service>.<operation>.useInfiniteQuery(
2020

2121
### Arguments
2222

23-
1. `parameters: { path, query, header } | QueryKey | undefined`
23+
1. `parameters: { path, query, header, body } | InfiniteQueryKey | undefined`
2424
- **Required only if OpenAPI specification defines required parameters**
2525
- If the operation has no required parameters according to OpenAPI, you can omit this argument
26-
- `parameters` will be used to generate the `QueryKey`
27-
- Instead of an object with `{path, query, header}`, you can pass a `QueryKey` as an array
26+
- `parameters` will be used to generate the _Infinite Query Key_
27+
- For operations generated with `--queryable-write-operations`, query parameters may also include `body`
28+
- In that mode, `body` is part of the infinite query key and cache identity
29+
- Mutation calls keep `body` as a separate top-level argument
30+
- Instead of an object with `{ path, query, header, body }`, you can pass a typed `InfiniteQueryKey` from `getInfiniteQueryKey(...)`
2831
which is also strictly-typed ✨
29-
- If operation does not require parameters, you must pass an empty object `{}` for strictness
3032

3133
2. `infiniteQueryOptions?: UseInfiniteQueryOptions`
3234
- **Optional**, represents the options of the [_useInfiniteQuery(...) 🌴_](https://tanstack.com/query/latest/docs/framework/react/reference/useInfiniteQuery) Hook

‎website/docs/hooks/useIsFetching.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ const queriesNumber = api.<service>.<operation>.useIsFetching(
2020
1. `filters?: QueryFiltersByParameters | QueryFiltersByQueryKey`
2121
- **Optional**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters)
2222
to be used. If not provided, _all_ normal and _Infinite_ queries will be used to filter.
23-
- `filters.parameters: { path, query, header }` will be used for filtering queries by parameters
23+
- `filters.parameters: { path, query, header, body }` filters queries by operation parameters.
24+
- For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity.
2425
- `filters.infinite: boolean` will be used to filter infinite or normal queries
2526
- `filters.queryKey: QueryKey` will be used for filtering queries by _QueryKey_ instead of parameters
2627
- `filters.queryKey` and `filters.parameters` are mutually exclusive

‎website/docs/hooks/useQueries.mdx‎

Lines changed: 75 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
sidebar_label: useQueries()
33
---
44

5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
58
# useQueries(...)
69

710
The Hook enables you to concurrently execute multiple asynchronous data fetching operations.
@@ -20,7 +23,8 @@ const queries = api.<service>.<operation>.useQueries(
2023
- **Required**, represents the options for queries, see [_useQueries(...) 🌴_](https://tanstack.com/query/latest/docs/framework/react/reference/useQueries) documentation
2124
- `options.queries: QueryOptions[]`
2225
- **Required** array of _Queries_ to be executed
23-
- `parameters: { path, query, header }` will be used for the request
26+
- `parameters: { path, query, header, body }` will be used for the request
27+
- For operations generated with `--queryable-write-operations`, `body` is part of the query key and cache identity
2428
- `queryKey: QueryKey` will be used for the request instead of the `parameters`
2529
- `queryKey` and `parameters` are mutually exclusive
2630
- `options.combine?: (result: UseQueriesResults) => TCombinedResult`
@@ -37,54 +41,77 @@ during code generation.
3741

3842
### Example
3943

40-
```tsx
41-
import { createAPIClient } from './api'; // generated by OpenAPI Qraft
42-
43-
import { requestFn } from '@openapi-qraft/react';
44-
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
45-
46-
const queryClient = new QueryClient();
47-
48-
const api = createAPIClient({
49-
requestFn,
50-
queryClient,
51-
baseUrl: 'https://api.sandbox.monite.com/v1',
52-
});
53-
54-
const useEntityQueries = () => {
55-
/**
56-
* Initiates two concurrent GET requests:
57-
* ###
58-
* GET /entities/3e3e-3e3e-3e3e
59-
* x-monite-version: 2023-09-01
60-
* ###
61-
* GET /entities/5c5c-5c5c-5c5c
62-
* x-monite-version: 2023-09-01
63-
**/
64-
return api.entities.getEntities.useQueries({
65-
queries: [
66-
{
67-
parameters: {
68-
header: {
69-
'x-monite-version': '2023-09-01',
44+
<Tabs>
45+
<TabItem value="get-queries" label="GET queries" default>
46+
```tsx
47+
import { createAPIClient } from './api'; // generated by OpenAPI Qraft
48+
49+
import { requestFn } from '@openapi-qraft/react';
50+
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
51+
52+
const queryClient = new QueryClient();
53+
54+
const api = createAPIClient({
55+
requestFn,
56+
queryClient,
57+
baseUrl: 'https://api.sandbox.monite.com/v1',
58+
});
59+
60+
const useEntityQueries = () => {
61+
return api.entities.getEntities.useQueries({
62+
queries: [
63+
{
64+
parameters: {
65+
header: { 'x-monite-version': '2023-09-01' },
66+
path: { entity_id: '3e3e-3e3e-3e3e' },
67+
},
7068
},
71-
path: {
72-
entity_id: '3e3e-3e3e-3e3e',
69+
{
70+
parameters: {
71+
header: { 'x-monite-version': '2023-09-01' },
72+
path: { entity_id: '5c5c-5c5c-5c5c' },
73+
},
7374
},
74-
},
75+
],
76+
combine: (results) => results.map((result) => result.data),
77+
});
78+
};
79+
```
80+
</TabItem>
81+
<TabItem value="queryable-write" label={<span>With <code>body</code></span>}>
82+
```tsx
83+
const firstSearch = {
84+
header: { 'x-monite-version': '1' },
85+
path: { approval_policy_id: '2' },
86+
body: {
87+
name: 'New Name',
88+
description: 'New Description',
7589
},
76-
{
77-
parameters: {
78-
header: {
79-
'x-monite-version': '2023-09-01',
80-
},
81-
path: {
82-
entity_id: '5c5c-5c5c-5c5c',
83-
},
84-
},
90+
};
91+
92+
const secondSearchParameters = {
93+
...firstSearch,
94+
body: {
95+
name: 'Another Name',
96+
description: 'Another Description',
8597
},
86-
],
87-
combine: (results) => results.map((result) => result.data),
88-
});
89-
}
90-
```
98+
};
99+
100+
const secondSearchQueryKey =
101+
api.approvalPolicies.patchApprovalPoliciesId.getQueryKey(
102+
secondSearchParameters
103+
);
104+
105+
const results = api.approvalPolicies.patchApprovalPoliciesId.useQueries({
106+
queries: [
107+
{ parameters: firstSearch },
108+
{ queryKey: secondSearchQueryKey },
109+
],
110+
});
111+
112+
// Never pass `secondSearchParameters` as `queryKey` directly.
113+
// `getQueryKey(...)` builds the tuple shape TanStack Query expects.
114+
// `firstSearch.body` and `secondSearchParameters.body` produce different cache entries.
115+
```
116+
</TabItem>
117+
</Tabs>

‎website/docs/hooks/useQuery.mdx‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,13 @@ const query = api.<service>.<operation>.useQuery(
2727

2828
### Arguments
2929

30-
1. `parameters: { path, query, header, body? } | QueryKey | void`
30+
1. `parameters: { path, query, header, body } | QueryKey | void`
3131
- **Required only if OpenAPI specification defines required parameters**
3232
- If the operation has no required parameters according to OpenAPI, you can omit this argument
3333
- `parameters` will be used to generate the `QueryKey`
34-
- For write operations (when using `--queryable-write-operations`), you can include a `body` parameter
34+
- For operations generated with `--queryable-write-operations`, query parameters may also include `body`
35+
- In that mode, `body` is part of the query key and cache identity for query hooks and query-client methods
36+
- Mutation calls keep `body` as a separate top-level argument
3537
- Instead of an object with `{ path, query, header, body }`, you can pass a `QueryKey` as an array
3638
which is also strictly-typed
3739

‎website/docs/hooks/useSuspenseInfiniteQuery.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,15 @@ const query = api.<service>.<operation>.useSuspenseInfiniteQuery(
1818

1919
### Arguments
2020

21-
1. `parameters: { path, query, header } | QueryKey | undefined`
21+
1. `parameters: { path, query, header, body } | InfiniteQueryKey | undefined`
2222
- **Required only if OpenAPI specification defines required parameters**
2323
- If the operation has no required parameters according to OpenAPI, you can omit this argument
24-
- `parameters` will be used to generate the `QueryKey`
25-
- Instead of an object with `{path, query, header}`, you can pass a `QueryKey` as an array
24+
- `parameters` will be used to generate the _Infinite Query Key_
25+
- For operations generated with `--queryable-write-operations`, query parameters may also include `body`
26+
- In that mode, `body` is part of the infinite query key and cache identity
27+
- Mutation calls keep `body` as a separate top-level argument
28+
- Instead of an object with `{ path, query, header, body }`, you can pass a typed `InfiniteQueryKey` from `getInfiniteQueryKey(...)`
2629
which is also strictly-typed ✨
27-
- If operation does not require parameters, you must pass an empty object `{}` for strictness
2830

2931
2. `suspenseInfiniteQueryOptions?: UseSuspenseInfiniteQueryOptions`
3032
- **Optional**, represents the options of the

‎website/docs/hooks/useSuspenseQueries.mdx‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ const result = api.<service>.<operation>.useSuspenseQueries(
2323
- **Required**, represents the options for queries, see [_useSuspenseQueries(...) 🌴_](https://tanstack.com/query/latest/docs/framework/react/reference/useSuspenseQueries) documentation
2424
- `options.queries: QueryOptions[]`
2525
- **Required** array of _Queries_ to be executed
26-
- `parameters: { path, query, header }` will be used for the request
26+
- `parameters: { path, query, header, body }` will be used for the request
27+
- For operations generated with `--queryable-write-operations`, `body` is part of the query key and cache identity
2728
- `queryKey: QueryKey` will be used for the request instead of the `parameters`
2829
- `queryKey` and `parameters` are mutually exclusive
2930
- `options.combine?: (result: UseQueriesResults) => TCombinedResult`
@@ -109,3 +110,30 @@ export default function() {
109110
)
110111
}
111112
```
113+
114+
### Queryable Write Operations
115+
116+
For operations generated with `--queryable-write-operations`, `useSuspenseQueries` accepts the same `parameters.body`
117+
shape as `useQueries`. Each distinct body is part of the query key and creates a distinct cache entry.
118+
119+
```tsx
120+
const queryKey =
121+
api.approvalPolicies.patchApprovalPoliciesId.getQueryKey({
122+
header: { 'x-monite-version': '1' },
123+
path: { approval_policy_id: '2' },
124+
body: { name: 'Another Name' },
125+
});
126+
127+
const results = api.approvalPolicies.patchApprovalPoliciesId.useSuspenseQueries({
128+
queries: [
129+
{
130+
parameters: {
131+
header: { 'x-monite-version': '1' },
132+
path: { approval_policy_id: '2' },
133+
body: { name: 'New Name' },
134+
},
135+
},
136+
{ queryKey },
137+
],
138+
});
139+
```

‎website/docs/hooks/useSuspenseQuery.mdx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,15 @@ const result = api.<service>.<operation>.useSuspenseQuery(
2020

2121
### Arguments
2222

23-
1. `parameters: { path, query, header } | QueryKey | void`
23+
1. `parameters: { path, query, header, body } | QueryKey | void`
2424
- **Required only if OpenAPI specification defines required parameters**
2525
- If the operation has no required parameters according to OpenAPI, you can omit this argument
2626
- `parameters` will be used to generate the `QueryKey`
27-
- Instead of an object with `{path, query, header}`, you can pass a `QueryKey` as an array
27+
- For operations generated with `--queryable-write-operations`, query parameters may also include `body`
28+
- In that mode, `body` is part of the query key and cache identity for query hooks and query-client methods
29+
- Mutation calls keep `body` as a separate top-level argument
30+
- Instead of an object with `{ path, query, header, body }`, you can pass a `QueryKey` as an array
2831
which is also strictly-typed ✨
29-
- If operation does not require parameters, you must pass an empty object `{}` for strictness
3032

3133
2. `queryOptions?: UseQueryOptions`
3234
- **Optional**, represents the options of the [_useSuspenseQuery(...) 🌴_](https://tanstack.com/query/latest/docs/framework/react/reference/useSuspenseQuery) Hook

‎website/docs/query-client/cancelQueries.mdx‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@ guide for more information.
2525
1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey`
2626
- **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters)
2727
to be used, strictly-typed ✨
28-
- `filters.parameters: { path, query, header }` will be used for filtering queries by parameters
28+
- `filters.parameters: { path, query, header, body }` filters queries by operation parameters.
29+
- For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity.
2930
- `filters.infinite?: boolean` will be used to filter infinite or normal queries, **Required** if `predicate` is provided
3031
- `filters.queryKey?: QueryKey` will be used for filtering queries by _QueryKey_ instead of ~~`parameters`~~
3132
- `filters.queryKey` and `filters.parameters` are mutually exclusive
@@ -45,7 +46,8 @@ guide for more information.
4546
1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey`
4647
- **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters)
4748
to be used, strictly-typed ✨
48-
- `filters.parameters: { path, query, header }` will be used for filtering queries by parameters
49+
- `filters.parameters: { path, query, header, body }` filters queries by operation parameters.
50+
- For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity.
4951
- `filters.infinite?: boolean` will be used to filter infinite or normal queries, **Required** if `predicate` is provided
5052
- `filters.queryKey?: QueryKey` will be used for filtering queries by _QueryKey_ instead of ~~`parameters`~~
5153
- `filters.queryKey` and `filters.parameters` are mutually exclusive

‎website/docs/query-client/ensureInfiniteQueryData.mdx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,12 @@ const result = api.<service>.<operation>.ensureInfiniteQueryData({
2222
```
2323

2424
### Arguments
25-
1. - `parameters: { path, query, header } | QueryKey | void`
25+
1. - `parameters: { path, query, header, body } | InfiniteQueryKey | void`
2626
- OpenAPI request parameters for the query, strictly-typed ✨
27-
- `parameters` will be used to generate the `QueryKey`
27+
- `parameters` will be used to generate the _Infinite Query Key_
28+
- For operations generated with `--queryable-write-operations`, query parameters may also include `body`
29+
- In that mode, `body` is part of the infinite query key and cache identity
30+
- Mutation calls keep `body` as a separate top-level argument
2831
- `fetchInfiniteQueryOptions?: FetchInfiniteQueryOptions`
2932
- `requestFn?: RequestFn`
3033
- **Optional**, a function that will be used to execute the request

0 commit comments

Comments
 (0)