docs: add mutation-options.md

Author: minchodang

docs/.vitepress/en.ts

@@ -76,6 +76,7 @@ export default defineConfig({
             { text: "useSuspenseQuery", link: "/use-suspense-query" },
             { text: "useInfiniteQuery", link: "/use-infinite-query" },
             { text: "queryOptions", link: "/query-options" },
+            { text: "mutationOptions", link: "/mutation-options" },
           ],
         },
         {

docs/openapi-react-query/mutation-options.md

@@ -0,0 +1,88 @@
+---
+title: mutationOptions
+---
+
+# {{ $frontmatter.title }}
+
+The `mutationOptions` method lets you build type-safe [Mutation Options](https://tanstack.com/query/latest/docs/framework/react/reference/mutationOptions) that plug directly into React Query APIs.
+
+Use it whenever you want to call `$api` mutations but still provide your own `useMutation` (or other mutation consumer) configuration. The helper wires up the correct `mutationKey`, generates a fetcher that calls your OpenAPI endpoint, and preserves the inferred `data` and `error` types.
+
+## Examples
+
+Rewriting the [useMutation example](use-mutation#example) to use `mutationOptions`.
+
+::: code-group
+
+```tsx [src/app.tsx]
+import { useMutation } from '@tanstack/react-query';
+import { $api } from './api';
+
+export const App = () => {
+    const updateUser = useMutation(
+        $api.mutationOptions('patch', '/users/{user_id}', {
+            onSuccess: (data, variables) => {
+                console.log('Updated', variables.params?.path?.user_id, data.firstname);
+            },
+        })
+    );
+
+    return (
+        <button
+            onClick={() =>
+                updateUser.mutate({
+                    params: { path: { user_id: 5 } },
+                    body: { firstname: 'John' },
+                })
+            }
+        >
+            Update
+        </button>
+    );
+};
+```
+
+```ts [src/api.ts]
+import createFetchClient from 'openapi-fetch';
+import createClient from 'openapi-react-query';
+import type { paths } from './my-openapi-3-schema'; // generated by openapi-typescript
+
+const fetchClient = createFetchClient<paths>({
+    baseUrl: 'https://myapi.dev/v1/',
+});
+export const $api = createClient(fetchClient);
+```
+
+:::
+
+::: info Good to Know
+
+`$api.useMutation` uses the same fetcher and key contract as `mutationOptions`. Reach for `mutationOptions` when you need to share mutation configuration across components or call React Query utilities such as `queryClient.mutationDefaults`.
+
+:::
+
+## API
+
+```tsx
+const options = $api.mutationOptions(method, path, mutationOptions);
+```
+
+**Arguments**
+
+- `method` **(required)**
+    - HTTP method of the OpenAPI operation.
+    - Also used as the first element of the mutation key.
+- `path` **(required)**
+    - Pathname of the OpenAPI operation.
+    - Must be valid for the given method in your generated schema.
+    - Used as the second element of the mutation key.
+- `mutationOptions`
+    - Optional `UseMutationOptions` for React Query.
+    - You can set callbacks (`onSuccess`, `onSettled`, …), retry behaviour, and every option except `mutationKey` and `mutationFn` (those are provided for you).
+
+**Returns**
+
+- [Mutation Options](https://tanstack.com/query/latest/docs/framework/react/reference/mutationOptions)
+    - `mutationKey` is `[method, path]`.
+    - `mutationFn` is a strongly typed fetcher that calls `openapi-fetch` with your `init` payload.
+    - `data` and `error` types match the OpenAPI schema, so `variables` inside callbacks are typed as the request shape.