RND-2311: enums for server url in openapi block

.changeset/long-shrimps-judge.md

@@ -0,0 +1,6 @@
+---
+'@gitbook/react-openapi': minor
+'gitbook': minor
+---
+
+Allow selection of server url

packages/gitbook/src/app/(site)/(content)/[[...pathname]]/page.tsx

@@ -3,6 +3,7 @@ import { Metadata, Viewport } from 'next';
 import { notFound, redirect } from 'next/navigation';
 import React from 'react';
 
+import { serverUrlCache } from '@/components/DocumentView/OpenAPI/ServerUrlCache';
 import { PageAside } from '@/components/PageAside';
 import { PageBody, PageCover } from '@/components/PageBody';
 import { PageHrefContext, absoluteHref, pageHref } from '@/lib/links';
@@ -26,6 +27,8 @@ export default async function Page(props: {
 }) {
     const { params, searchParams } = props;
 
+    serverUrlCache.parse(searchParams);
+
     const {
         content: contentPointer,
         contentTarget,

packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPI.tsx

@@ -7,6 +7,8 @@ import { LoadingPane } from '@/components/primitives';
 import { fetchOpenAPIBlock } from '@/lib/openapi';
 import { tcls } from '@/lib/tailwind';
 
+import OpenAPIClientStateContainer from './OpenAPIClientStateContainer';
+import { serverUrlCache } from './ServerUrlCache';
 import { BlockProps } from '../Block';
 import { PlainCodeBlock } from '../CodeBlock';
 
@@ -17,7 +19,7 @@ import './scalar.css';
  * Render an OpenAPI block.
  */
 export async function OpenAPI(props: BlockProps<DocumentBlockSwagger>) {
-    const { block, style } = props;
+    const { style } = props;
     return (
         <div className={tcls('w-full', 'flex', 'flex-row', style, 'max-w-full')}>
             <React.Suspense fallback={<OpenAPIFallback />}>
@@ -45,21 +47,30 @@ async function OpenAPIBody(props: BlockProps<DocumentBlockSwagger>) {
         return null;
     }
 
+    // To update the code sample we need to re-render the server component
+    // so reading the cached value from search params
+    const serverUrl = serverUrlCache.get('serverUrl');
+
     return (
-        <OpenAPIOperation
-            data={data}
-            context={{
-                icons: {
-                    chevronDown: <Icon icon="chevron-down" />,
-                    chevronRight: <Icon icon="chevron-right" />,
-                },
-                CodeBlock: PlainCodeBlock,
-                defaultInteractiveOpened: context.mode === 'print',
-                id: block.meta?.id,
-                blockKey: block.key,
-            }}
-            className="openapi-block"
-        />
+        <OpenAPIClientStateContainer block={block} servers={data.servers}>
+            <OpenAPIOperation
+                data={data}
+                context={{
+                    icons: {
+                        chevronDown: <Icon icon="chevron-down" />,
+                        chevronRight: <Icon icon="chevron-right" />,
+                        edit: <Icon icon="edit" />,
+                        editDone: <Icon icon="check" />,
+                    },
+                    CodeBlock: PlainCodeBlock,
+                    defaultInteractiveOpened: context.mode === 'print',
+                    id: block.meta?.id,
+                    blockKey: block.key,
+                    serverUrl,
+                }}
+                className="openapi-block"
+            />
+        </OpenAPIClientStateContainer>
     );
 }
 

packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPIClientStateContainer.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { DocumentBlock } from '@gitbook/api';
+import { OpenAPIClientState } from '@gitbook/react-openapi/client';
+import { useRouter, useSearchParams } from 'next/navigation';
+import { OpenAPIV3 } from 'openapi-types';
+import * as React from 'react';
+
+/**
+ * Client component that wraps `OpenAPIClientState` so we can
+ * use some hooks (e.g. useRouter) in the `onUpdate` callback.
+ */
+export default function OpenAPIClientStateContainer(props: {
+    children: React.ReactNode;
+    block: DocumentBlock;
+    servers: OpenAPIV3.ServerObject[];
+}) {
+    const { block, children, servers } = props;
+    const [isPending, startTransition] = React.useTransition();
+    const router = useRouter();
+    const searchParams = useSearchParams();
+
+    return (
+        <OpenAPIClientState
+            isPending={isPending}
+            servers={servers}
+            params={
+                searchParams.get('block') === block.key
+                    ? Object.fromEntries(searchParams.entries())
+                    : undefined
+            }
+            onUpdate={async (params) => {
+                startTransition(() => {
+                    const queryParams = new URLSearchParams(params ?? '');
+                    router.replace(`?${queryParams}`, { scroll: false });
+                });
+            }}
+        >
+            {children}
+        </OpenAPIClientState>
+    );
+}

packages/gitbook/src/components/DocumentView/OpenAPI/ServerUrlCache.tsx

@@ -0,0 +1,5 @@
+import { createSearchParamsCache, parseAsString } from 'nuqs/server';
+
+export const serverUrlCache = createSearchParamsCache({
+    serverUrl: parseAsString,
+});

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -57,7 +57,7 @@
 /** URL */
 
 .openapi-url {
-    @apply font-mono text-sm text-dark/8 dark:text-light/8;
+    @apply flex items-center font-mono text-sm text-dark/8 dark:text-light/8;
 }
 
 .openapi-url-var {
@@ -364,3 +364,24 @@
 .openapi-markdown > *:last-child {
     @apply mb-0;
 }
+
+.openapi-select-button,
+.openapi-edit-button {
+    @apply p-0.5 inline-flex text-dark/6 dark:text-light/6 hover:opacity-8;
+}
+
+.openapi-edit-button {
+    @apply p-0.5 ml-4 size-4;
+}
+
+.openapi-edit-button > * {
+    @apply size-full;
+}
+
+.openapi-select-button {
+    @apply leading-[1cap] disabled:opacity-5;
+}
+
+.openapi-pending {
+    @apply opacity-5;
+}

packages/gitbook/src/components/PageBody/PageBody.tsx

@@ -50,7 +50,6 @@ export function PageBody(props: {
     const language = getSpaceLanguage(customization);
     const updatedAt = page.updatedAt ?? page.createdAt;
     const shouldHighlightCode = createHighlightingContext();
-
     return (
         <>
             <main

packages/react-openapi/package.json

@@ -6,7 +6,8 @@
             "types": "./dist/index.d.ts",
             "development": "./src/index.ts",
             "default": "./dist/index.js"
-        }
+        },
+        "./client": "./src/client.ts"
     },
     "version": "0.6.0",
     "dependencies": {

packages/react-openapi/src/OpenAPIClientStateContext.tsx

@@ -0,0 +1,92 @@
+'use client';
+
+import * as React from 'react';
+import { getServersURL } from './utils';
+import { OpenAPIV3 } from 'openapi-types';
+
+type OpenAPIClientStateContextProps = {
+    /**
+     * Whether client state updates are in a pending state,
+     * i.e. is a transition in progress.
+     */
+    isPending?: boolean;
+    /**
+     * The server url
+     */
+    serverUrl?: string;
+    /**
+     * The current state
+     */
+    state?: Record<string, string> | null;
+    /**
+     * Callback for when the client state is updated
+     */
+    onUpdate: (params: Record<string, string> | null) => void;
+};
+
+const OpenAPIClientStateContext = React.createContext<OpenAPIClientStateContextProps | null>(null);
+
+export function useOpenAPIClientState() {
+    return React.useContext(OpenAPIClientStateContext);
+}
+
+/**
+ * Control client state for an OpenAPI operation
+ */
+export function OpenAPIClientState(props: {
+    children: React.ReactNode;
+    servers: OpenAPIV3.ServerObject[];
+    isPending?: boolean;
+    params?: Record<string, string>;
+    onUpdate: OpenAPIClientStateContextProps['onUpdate'];
+}) {
+    const { children, servers, isPending, params, onUpdate } = props;
+
+    const clientState = React.useMemo(() => {
+        if (!params) {
+            return null;
+        }
+        return parseClientStateModifiers(servers, params);
+    }, [servers, params]);
+    const serverUrl = getServersURL(servers, clientState ?? undefined);
+
+    return (
+        <OpenAPIClientStateContext.Provider
+            value={{
+                isPending,
+                state: clientState,
+                serverUrl,
+                onUpdate,
+            }}
+        >
+            {children}
+        </OpenAPIClientStateContext.Provider>
+    );
+}
+
+function parseClientStateModifiers(
+    servers: OpenAPIV3.ServerObject[],
+    params: Record<string, string>,
+) {
+    if (!servers) {
+        return null;
+    }
+    const serverQueryParam = params['server'];
+    const serverIndex =
+        serverQueryParam && !isNaN(Number(serverQueryParam))
+            ? Math.max(0, Math.min(Number(serverQueryParam), servers.length - 1))
+            : 0;
+    const server = servers[serverIndex];
+    return server
+        ? Object.keys(server.variables ?? {}).reduce<Record<string, string>>(
+              (result, key) => {
+                  const selection = params[key];
+                  if (!isNaN(Number(selection))) {
+                      result[key] = selection;
+                  }
+                  return result;
+              },
+              { server: `${serverIndex}`, edit: params['edit'] },
+          )
+        : null;
+}

packages/react-openapi/src/OpenAPICodeSample.tsx

@@ -4,10 +4,9 @@ import { CodeSampleInput, codeSampleGenerators } from './code-samples';
 import { OpenAPIOperationData, toJSON } from './fetchOpenAPIOperation';
 import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
 import { InteractiveSection } from './InteractiveSection';
-import { getServersURL } from './OpenAPIServerURL';
 import { ScalarApiButton } from './ScalarApiButton';
 import { OpenAPIContextProps } from './types';
-import { noReference } from './utils';
+import { getServersURL, noReference } from './utils';
 
 /**
  * Display code samples to execute the operation.
@@ -49,14 +48,11 @@ export function OpenAPICodeSample(props: {
         }
     });
 
+    const serverUrl = context.serverUrl ?? getServersURL(data.servers);
     const requestBody = noReference(data.operation.requestBody);
     const requestBodyContent = requestBody ? Object.entries(requestBody.content)[0] : undefined;
-
     const input: CodeSampleInput = {
-        url:
-            getServersURL(data.servers) +
-            data.path +
-            (searchParams.size ? `?${searchParams.toString()}` : ''),
+        url: serverUrl + data.path + (searchParams.size ? `?${searchParams.toString()}` : ''),
         method: data.method,
         body: requestBodyContent
             ? generateMediaTypeExample(requestBodyContent[1], { onlyRequired: true })

packages/react-openapi/src/OpenAPIOperation.tsx

@@ -37,7 +37,7 @@ export function OpenAPIOperation(props: {
                     {operation.description ? (
                         <Markdown className="openapi-description" source={operation.description} />
                     ) : null}
-                    <div className="openapi-target">
+                    <div className="openapi-target flex items-center">
                         <span
                             className={classNames(
                                 'openapi-method',
@@ -47,8 +47,11 @@ export function OpenAPIOperation(props: {
                             {method.toUpperCase()}
                         </span>
                         <span className="openapi-url">
-                            <OpenAPIServerURL servers={servers} />
-                            {path}
+                            <OpenAPIServerURL
+                                servers={servers}
+                                context={clientContext}
+                                path={path}
+                            />
                         </span>
                     </div>
                 </div>