Skip to content

Commit fa6c3c4

Browse files
kerwanpkerwanp
committed
Write documentation for openapi-react-query
1 parent 281d82f commit fa6c3c4

File tree

8 files changed

+371
-4
lines changed

8 files changed

+371
-4
lines changed

‎docs/.vitepress/en.ts

+10
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,16 @@ export const en = defineConfig({
6868
{ text: "About", link: "/openapi-fetch/about" },
6969
],
7070
},
71+
{
72+
text: "openapi-react-query",
73+
items: [
74+
{ text: "Getting Started", link: "/openapi-react-query/" },
75+
{ text: "useQuery", link: "/openapi-react-query/use-query" },
76+
{ text: "useMutation", link: "/openapi-react-query/use-mutation" },
77+
{ text: "useSuspenseQuery", link: "/openapi-react-query/use-suspense-query" },
78+
{ text: "About", link: "/openapi-react-query/about" },
79+
],
80+
},
7181
],
7282
},
7383
search: {

‎docs/data/contributors.json

+1-1
Large diffs are not rendered by default.

‎docs/openapi-react-query/about.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: About openapi-react-query
3+
description: openapi-react-query Project Goals and contributors
4+
---
5+
<script setup>
6+
import { VPTeamMembers } from 'vitepress/theme';
7+
import contributors from '../data/contributors.json';
8+
</script>
9+
10+
# About
11+
12+
## Project Goals
13+
14+
1. Types should be strict and inferred automatically from OpenAPI schemas with the absolute minimum number of generics needed.
15+
2. Respect the original `@tanstack/react-query` APIs while reducing boilerplate.
16+
3. Be as light and performant as possible.
17+
18+
## Contributors
19+
20+
This library wouldn’t be possible without all these amazing contributors:
21+
22+
<VPTeamMembers size="small" :members="contributors['openapi-react-query']" />
23+

‎docs/openapi-react-query/index.md

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: openapi-react-query
3+
---
4+
# Introduction
5+
6+
openapi-react-query is a type-safe tiny wrapper (1 kb) around [@tanstack/react-query](https://tanstack.com/query/latest/docs/framework/react/overview) to work with OpenAPI schema.
7+
8+
It works by using [openapi-fetch](../openapi-fetch/) and [openapi-typescript](../introduction) so you get all the following features:
9+
10+
- ✅ No typos in URLs or params.
11+
- ✅ All parameters, request bodies, and responses are type-checked and 100% match your schema
12+
- ✅ No manual typing of your API
13+
- ✅ Eliminates `any` types that hide bugs
14+
- ✅ Also eliminates `as` type overrides that can also hide bugs
15+
16+
::: code-group
17+
18+
```tsx [src/my-component.ts]
19+
import createFetchClient from "openapi-fetch";
20+
import createClient from "openapi-react-query";
21+
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
22+
23+
const fetchClient = createFetchClient<paths>({
24+
baseUrl: "https://myapi.dev/v1/",
25+
});
26+
const $api = createClient(fetchClient);
27+
28+
const MyComponent = () => {
29+
const { data, error, isLoading } = $api.useQuery(
30+
"get",
31+
"/blogposts/{post_id}",
32+
{
33+
params: {
34+
path: { post_id: 5 },
35+
},
36+
},
37+
);
38+
39+
if (isLoading || !data) return "Loading...";
40+
41+
if (error) return `An error occured: ${error.message}`;
42+
43+
return <div>{data.title}</div>;
44+
};
45+
```
46+
47+
:::
48+
49+
## Setup
50+
51+
Install this library along with [openapi-fetch](../openapi-fetch/) and [openapi-typescript](../introduction):
52+
53+
```bash
54+
npm i openapi-react-query openapi-fetch
55+
npm i -D openapi-typescript typescript
56+
```
57+
58+
::: tip Highly recommended
59+
60+
Enable [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) in your `tsconfig.json` ([docs](/advanced#enable-nouncheckedindexaccess-in-your-tsconfigjson))
61+
62+
:::
63+
64+
Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:
65+
66+
```bash
67+
npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts
68+
```
69+
70+
## Basic usage
71+
72+
Once your types has been generated from your schema, you can create a [fetch client](../introduction.md), a react-query client and start querying your API.
73+
74+
::: code-group
75+
76+
```tsx [src/my-component.ts]
77+
import createFetchClient from "openapi-fetch";
78+
import createClient from "openapi-react-query";
79+
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
80+
81+
const fetchClient = createFetchClient<paths>({
82+
baseUrl: "https://myapi.dev/v1/",
83+
});
84+
const $api = createClient(fetchClient);
85+
86+
const MyComponent = () => {
87+
const { data, error, isLoading } = $api.useQuery(
88+
"get",
89+
"/blogposts/{post_id}",
90+
{
91+
params: {
92+
path: { post_id: 5 },
93+
},
94+
},
95+
);
96+
97+
if (isLoading || !data) return "Loading...";
98+
99+
if (error) return `An error occured: ${error.message}`;
100+
101+
return <div>{data.title}</div>;
102+
};
103+
```
104+
105+
:::
106+
107+
::: tip
108+
You can find more information about `createFetchClient` on the [openapi-fetch documentation](../openapi-fetch/index.md).
109+
:::
110+

‎docs/openapi-react-query/use-mutation.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: useQuery
3+
---
4+
# {{ $frontmatter.title }}
5+
6+
The `useMutation` method allows you to use the original [useMutation](https://tanstack.com/query/latest/docs/framework/react/guides/queries).
7+
8+
- The result is the same as the original function.
9+
- The `mutationKey` is `[method, path]`.
10+
- `data` and `error` are fully typed.
11+
12+
::: tip
13+
You can find more information about `useMutation` on the [@tanstack/react-query documentation](https://tanstack.com/query/latest/docs/framework/react/guides/mutations).
14+
:::
15+
16+
## Example
17+
18+
::: code-group
19+
20+
```tsx [src/app.tsx]
21+
import { $api } from "./api";
22+
23+
export const App = () => {
24+
const { mutate } = $api.useMutation("patch", "/users");
25+
26+
return (
27+
<button onClick={() => mutate({ body: { firstname: "John" } })}>
28+
Update
29+
</button>
30+
);
31+
};
32+
```
33+
34+
```ts [src/api.ts]
35+
import createFetchClient from "openapi-fetch";
36+
import createClient from "openapi-react-query";
37+
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
38+
39+
const fetchClient = createFetchClient<paths>({
40+
baseUrl: "https://myapi.dev/v1/",
41+
});
42+
export const $api = createClient(fetchClient);
43+
```
44+
45+
:::
46+
47+
## Api
48+
49+
```tsx
50+
const query = $api.useQuery(method, path, options, queryOptions);
51+
```
52+
53+
**Arguments**
54+
55+
- `method` **(required)**
56+
- The HTTP method to use for the request.
57+
- The method is used as key. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information.
58+
- `path` **(required)**
59+
- The pathname to use for the request.
60+
- Must be an available path for the given method in your schema.
61+
- The pathname is used as key. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information.
62+
- `queryOptions`
63+
- The original `useMutation` options.
64+
- [See more information](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation)
65+

‎docs/openapi-react-query/use-query.md

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: useQuery
3+
---
4+
# {{ $frontmatter.title }}
5+
6+
The `useQuery` method allows you to use the original [useQuery](https://tanstack.com/query/latest/docs/framework/react/guides/queries).
7+
8+
- The result is the same as the original function.
9+
- The `functionKey` is `[method, path, params]`.
10+
- `data` and `error` are fully typed.
11+
- You can pass queries options as fourth parameter.
12+
13+
::: tip
14+
You can find more information about `useQuery` on the [@tanstack/react-query documentation](https://tanstack.com/query/latest/docs/framework/react/guides/queries).
15+
:::
16+
17+
## Example
18+
19+
::: code-group
20+
21+
```tsx [src/app.tsx]
22+
import { $api } from "./api";
23+
24+
export const App = () => {
25+
const { data, error, isLoading } = $api.useQuery("get", "/users/{user_id}", {
26+
params: {
27+
path: { user_id: 5 },
28+
},
29+
});
30+
31+
if (!data || isLoading) return "Loading...";
32+
if (error) return `An error occured: ${error.message}`;
33+
34+
return <div>{data.firstname}</div>;
35+
};
36+
```
37+
38+
```ts [src/api.ts]
39+
import createFetchClient from "openapi-fetch";
40+
import createClient from "openapi-react-query";
41+
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
42+
43+
const fetchClient = createFetchClient<paths>({
44+
baseUrl: "https://myapi.dev/v1/",
45+
});
46+
export const $api = createClient(fetchClient);
47+
```
48+
49+
:::
50+
51+
## Api
52+
53+
```tsx
54+
const query = $api.useQuery(method, path, options, queryOptions);
55+
```
56+
57+
**Arguments**
58+
59+
- `method` **(required)**
60+
- The HTTP method to use for the request.
61+
- The method is used as key. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information.
62+
- `path` **(required)**
63+
- The pathname to use for the request.
64+
- Must be an available path for the given method in your schema.
65+
- The pathname is used as key. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information.
66+
- `options`
67+
- The fetch options to use for the request.
68+
- Only required if the OpenApi schema requires parameters.
69+
- The options `params` are used as key. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information.
70+
- `queryOptions`
71+
- The original `useQuery` options.
72+
- [See more information](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery)
73+

‎docs/openapi-react-query/use-suspense-query.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: useSuspenseQuery
3+
---
4+
# {{ $frontmatter.title }}
5+
6+
The `useSuspenseQuery` method allows you to use the original [useSuspenseQuery](https://tanstack.com/query/latest/docs/framework/react/guides/suspense).
7+
8+
- The result is the same as the original function.
9+
- The `functionKey` is `[method, path, params]`.
10+
- `data` and `error` are fully typed.
11+
- You can pass queries options as fourth parameter.
12+
13+
::: tip
14+
You can find more information about `useSuspenseQuery` on the [@tanstack/react-query documentation](https://tanstack.com/query/latest/docs/framework/react/guides/suspense).
15+
:::
16+
17+
## Example
18+
19+
::: code-group
20+
21+
```tsx [src/app.tsx]
22+
import { ErrorBoundary } from "react-error-boundary";
23+
import { $api } from "./api";
24+
25+
const MyComponent = () => {
26+
const { data } = $api.useSuspenseQuery("get", "/users/{user_id}", {
27+
params: {
28+
path: { user_id: 5 },
29+
},
30+
});
31+
32+
return <div>{data.firstname}</div>;
33+
};
34+
35+
export const App = () => {
36+
return (
37+
<ErrorBoundary fallbackRender={({ error }) => `Error: ${error.message}`}>
38+
<MyComponent />
39+
</ErrorBoundary>
40+
);
41+
};
42+
```
43+
44+
```ts [src/api.ts]
45+
import createFetchClient from "openapi-fetch";
46+
import createClient from "openapi-react-query";
47+
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
48+
49+
const fetchClient = createFetchClient<paths>({
50+
baseUrl: "https://myapi.dev/v1/",
51+
});
52+
export const $api = createClient(fetchClient);
53+
```
54+
55+
:::
56+
57+
## Api
58+
59+
```tsx
60+
const query = $api.useSuspenseQuery(method, path, options, queryOptions);
61+
```
62+
63+
**Arguments**
64+
65+
- `method` **(required)**
66+
- The HTTP method to use for the request.
67+
- The method is used as key. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information.
68+
- `path` **(required)**
69+
- The pathname to use for the request.
70+
- Must be an available path for the given method in your schema.
71+
- The pathname is used as key. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information.
72+
- `options`
73+
- The fetch options to use for the request.
74+
- Only required if the OpenApi schema requires parameters.
75+
- The options `params` are used as key. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information.
76+
- `queryOptions`
77+
- The original `useSuspenseQuery` options.
78+
- [See more information](https://tanstack.com/query/latest/docs/framework/react/reference/useSuspenseQuery)
79+

‎docs/scripts/update-contributors.js

+10-3
Original file line numberDiff line numberDiff line change
@@ -182,12 +182,19 @@ export const OPENAPI_FETCH_CONTRIBUTORS = [
182182
]),
183183
];
184184

185+
export const OPENAPI_REACT_QUERY_CONTRIBUTORS = [...new Set(["drwpow", "kerwanp"])];
186+
185187
async function main() {
186-
const total = [...OPENAPI_TS_CONTRIBUTORS, OPENAPI_FETCH_CONTRIBUTORS].length;
188+
const total = [...OPENAPI_TS_CONTRIBUTORS, OPENAPI_FETCH_CONTRIBUTORS, OPENAPI_REACT_QUERY_CONTRIBUTORS].length;
187189
let i = 0;
188190
await Promise.all(
189-
["openapi-typescript", "openapi-fetch"].map(async (repo) => {
190-
const userlist = repo === "openapi-fetch" ? OPENAPI_FETCH_CONTRIBUTORS : OPENAPI_TS_CONTRIBUTORS;
191+
["openapi-typescript", "openapi-fetch", "openapi-react-query"].map(async (repo) => {
192+
const userlist =
193+
repo === "openapi-fetch"
194+
? OPENAPI_FETCH_CONTRIBUTORS
195+
: repo === "openapi-react-query"
196+
? OPENAPI_REACT_QUERY_CONTRIBUTORS
197+
: OPENAPI_TS_CONTRIBUTORS;
191198
for (const username of userlist) {
192199
// skip profiles that have been updated within the past week
193200
const { lastFetch } = contributors[repo].find((u) => u.username === username) ?? { lastFetch: 0 };

0 commit comments

Comments
 (0)