feat: update documentation for context-based API client usage and configuration

Author: radist2s

website/docs/codegen/cli/redocly-config.mdx

@@ -242,9 +242,47 @@ apis:
             - getInfiniteQueryKey
 ```
 
-::::info Context-based createAPIClient
-`context:<ContextName>` is a must-have for React Compiler compatibility because it keeps generated hooks static
-(API client can be created outside React components).
-Need full setup and runtime patterns? See
-[Context-based API Client](../openapi/create-api-client-function/context-api-client.mdx).
-::::
+#### Using Context for React Compiler Compatibility
+
+The `context` option generates a React Context that provides `queryClient`, `requestFn`, and `baseUrl` to the API client.
+This allows you to create the client **outside of React components**, making hooks static and compatible with React Compiler.
+
+```yaml
+apis:
+  main:
+    root: ./openapi.json
+    x-openapi-qraft:
+      plugin:
+        tanstack-query-react: true
+        openapi-typescript: true
+      output-dir: src/api
+      create-api-client-fn:
+        # React API client with Context support
+        createAPIClient:
+          context: APIClientContext           # Generate APIClientContext React Context
+          callbacks:
+            - useQuery
+            - useMutation
+            - setQueryData
+            - getQueryData
+            - getQueryKey
+            - getInfiniteQueryKey
+```
+
+With this configuration, you can create the API client outside of components:
+
+```tsx
+import { createAPIClient, APIClientContext } from './api';
+
+// Create outside component - hooks are static and React Compiler compatible
+const api = createAPIClient();
+
+function MyComponent() {
+  // Hooks read queryClient, requestFn, baseUrl from APIClientContext
+  const { data } = api.pets.getPets.useQuery();
+  return <div>{data?.length} pets</div>;
+}
+```
+
+For detailed documentation on using Context-based API clients, see the
+[Context-based API Client](../openapi/create-api-client-function/context-api-client.mdx) documentation.

website/docs/codegen/openapi/create-api-client-function/index.mdx

@@ -148,51 +148,30 @@ the necessary `requestFn`, `baseUrl` and `queryClient` for React Hooks.
     ```
   </TabItem>
 <TabItem value="multiple-api-versions" label={<span style={{verticalAlign: 'middle'}}>Multiple API versions and <em>React <code>Context</code></em></span>}>
-    In this example, we create multiple API clients that manage two different API versions, each with its own `QueryClient`.
-    This approach mounts and unmounts `QueryClient` instances during the lifecycle of the application.
+    This example demonstrates how to use multiple API clients with React Context. With the `context:` option
+    in CLI, you can generate an API client that retrieves `queryClient`, `requestFn`, and `baseUrl` from
+    React Context at render time.
 
-    This setup is particularly useful when you need to work with different API versions simultaneously, or when you're in the process
-    of migrating from one API version to another.
+    :::tip React Compiler Compatibility
+    Creating the API client **outside of the component** with the `context:` option makes hooks static,
+    allowing React Compiler to optimize them. If you create the client inside `useMemo`, hooks become
+    dynamic and cannot be optimized by React Compiler.
+    :::
 
     ```tsx title="src/MultipleAPIClientsApp.tsx"
-    import { createAPIClient as createAPIClientV1Basic } from './api-v1'; // generated by OpenAPI Qraft CLI (1️⃣)
-    import { createAPIClient as createAPIClientV2Basic } from './api-v2'; // generated by OpenAPI Qraft CLI (2️⃣)
-    import { requestFn, type CreateAPIBasicClientOptions, type CreateAPIQueryClientOptions } from '@openapi-qraft/react';
-    import { createContext, useContext, useMemo, useEffect, type ReactNode} from "react";
+    import { createAPIClient as createAPIClientV1, APIClientContextV1 } from './api-v1'; // generated with context:APIClientContextV1
+    import { createAPIClient as createAPIClientV2, APIClientContextV2 } from './api-v2'; // generated with context:APIClientContextV2
+    import { requestFn } from '@openapi-qraft/react';
+    import { useEffect, useState, type ReactNode } from "react";
     import { QueryClient } from '@tanstack/react-query'
 
-    // Hypothetical legacy API Client
-    function createAPIClientV1(options: CreateAPIQueryClientOptions) {
-      return createAPIClientV1Basic(options);
-    }
-
-    // New version API Client
-    function createAPIClientV2(options: CreateAPIQueryClientOptions) {
-      return createAPIClientV2Basic(options);
-    }
-
-    const MultipleAPIClientsContext = createContext<{
-      apiV1: ReturnType<typeof createAPIClientV1>; // 1️⃣
-      apiV2: ReturnType<typeof createAPIClientV2>; // 2️⃣
-    }>(null!);
+    // ⬇︎ Create API clients OUTSIDE of the component - hooks are static and React Compiler compatible
+    const apiV1 = createAPIClientV1(); // Uses APIClientContextV1 for options
+    const apiV2 = createAPIClientV2(); // Uses APIClientContextV2 for options
 
     export default function MultipleAPIClientsApp({ children }: { children: ReactNode }) {
-      const queryClient1 = useMemo(() => new QueryClient(), []);
-      const queryClient2 = useMemo(() => new QueryClient(), []);
-
-      // Hypothetical legacy API Client without Query Client feature
-      const apiV1 = useMemo(() => createAPIClientV1({
-        requestFn,
-        queryClient: queryClient1,
-        baseUrl: 'https://api.sandbox.monite.com/v1',
-      }), [queryClient1]);
-
-      // New version API Client with the modern features
-      const apiV2 = useMemo(() => createAPIClientV2({
-        requestFn,
-        queryClient: queryClient2,
-        baseUrl: 'https://api.sandbox.monite.com/v2',
-      }), [queryClient2]);
+      const [queryClient1] = useState(() => new QueryClient());
+      const [queryClient2] = useState(() => new QueryClient());
 
       useEffect(() => {
         queryClient1.mount();
@@ -204,18 +183,24 @@ the necessary `requestFn`, `baseUrl` and `queryClient` for React Hooks.
       }, [queryClient1, queryClient2]);
 
       return (
-        <MultipleAPIClientsContext.Provider value={{ apiV1, apiV2 }}>
-          {children}
-        </MultipleAPIClientsContext.Provider>
+        <APIClientContextV1.Provider value={{ requestFn, queryClient: queryClient1, baseUrl: 'https://api.example.com/v1' }}>
+          <APIClientContextV2.Provider value={{ requestFn, queryClient: queryClient2, baseUrl: 'https://api.example.com/v2' }}>
+            {children}
+          </APIClientContextV2.Provider>
+        </APIClientContextV1.Provider>
       );
     }
 
-    function YourComponents() {
-      const { apiV1, apiV2 } = useContext(MultipleAPIClientsContext);
+    function YourComponent() {
+      // ⬇︎ Use hooks directly - they read options from Context
+      const { data: v1Data } = apiV1.pets.getPets.useQuery();
+      const { data: v2Data } = apiV2.pets.getPets.useQuery();
 
-      // Use `apiV1` and `apiV2` as needed
-      // ...
+      return <div>...</div>;
     }
     ```
+
+    For more details on configuring and using the Context-based API client, see the
+    [Context-based API Client](./context-api-client.mdx) documentation.
   </TabItem>
 </Tabs>

website/docs/codegen/openapi/index.mdx

@@ -205,6 +205,10 @@ It is possible to use multiple plugins at the same time. For example, `--plugin
       - `all` - include all available callbacks (useQuery, useMutation, setQueryData, etc.)
       - `none` - don't include any callbacks by default (they must be specified when calling the function)
       - `useQuery,useMutation,...` - list of specific callbacks to include
+    - `context:<ContextName>` - Generate a React Context that provides `queryClient`, `requestFn`, and `baseUrl` to the API client.
+      When the API client is created without options, it reads these values from the Context at render time.
+      This enables creating the client **outside of React components**, making hooks static and compatible with React Compiler.
+      See [Context-based API Client](./create-api-client-function/context-api-client.mdx) for detailed documentation.
   - **Examples:**
     - `--create-api-client-fn createAPIClient services:all callbacks:all` - creates the `createAPIClient()` function that
       includes all services and all callbacks by default (_default_ behavior)
@@ -213,6 +217,9 @@ It is possible to use multiple plugins at the same time. For example, `--plugin
     building a **minimal bundle size** client where you explicitly control which services and callbacks to include.
     - `--create-api-client-fn createCustomClient filename:create-custom-api services:none callbacks:setQueryData,getQueryData` - creates
       the `createCustomClient()` function in the `create-custom-api.ts` file with no default services and only `setQueryData()` and `getQueryData()` callbacks
+    - `--create-api-client-fn createAPIClient context:APIClientContext callbacks:useQuery,useMutation` - creates
+      the `createAPIClient()` function with a generated `APIClientContext` React Context. When called without options,
+      the client reads `queryClient`, `requestFn`, and `baseUrl` from the Context
 
   ::::tip
   When generating multiple API client functions with different parameters, it might be more convenient to use a configuration file