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/(space)/(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 OpenAPIContext from './OpenAPIContext';
+import { serverUrlCache } from './ServerUrlCache';
 import { BlockProps } from '../Block';
 import { PlainCodeBlock } from '../CodeBlock';
 
@@ -45,21 +47,28 @@ async function OpenAPIBody(props: BlockProps<DocumentBlockSwagger>) {
         return null;
     }
 
+    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"
-        />
+        <OpenAPIContext block={block} data={data}>
+            <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"
+            />
+        </OpenAPIContext>
     );
 }
 

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

@@ -0,0 +1,38 @@
+'use client';
+
+import { DocumentBlock } from '@gitbook/api';
+import { OpenAPIOperationData } from '@gitbook/react-openapi';
+import { OpenAPIContextProvider } from '@gitbook/react-openapi/client';
+import { useRouter, useSearchParams } from 'next/navigation';
+import * as React from 'react';
+
+export default function OpenAPIContext(props: {
+    children: React.ReactNode;
+    block: DocumentBlock;
+    data: OpenAPIOperationData;
+}) {
+    const { block, children, data } = props;
+    const [isPending, startTransition] = React.useTransition();
+    const router = useRouter();
+    const searchParams = useSearchParams();
+
+    return (
+        <OpenAPIContextProvider
+            isPending={isPending}
+            data={data}
+            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}
+        </OpenAPIContextProvider>
+    );
+}

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,20 @@
 .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;
+}

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

@@ -54,7 +54,6 @@ export function PageBody(props: {
         'siteId' in contentPointer
             ? { organizationId: contentPointer.organizationId, siteId: contentPointer.siteId }
             : undefined;
-
     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/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/OpenAPIContextProvider.tsx

@@ -0,0 +1,72 @@
+'use client';
+
+import * as React from 'react';
+import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+import { getServersURL } from './utils';
+
+type OpenAPIContextProps = {
+    isPending?: boolean;
+    serverUrl?: string;
+    state?: Record<string, string> | null;
+    onUpdate: (params: Record<string, string> | null) => void;
+};
+const OpenAPIContext = React.createContext<OpenAPIContextProps | null>(null);
+
+export function useOpenAPIContext() {
+    return React.useContext(OpenAPIContext);
+}
+
+export function OpenAPIContextProvider(props: {
+    children: React.ReactNode;
+    data: OpenAPIOperationData;
+    isPending?: boolean;
+    params?: Record<string, string>;
+    onUpdate: OpenAPIContextProps['onUpdate'];
+}) {
+    const { children, data, isPending, params, onUpdate } = props;
+
+    const clientState = React.useMemo(() => {
+        if (!params) {
+            return null;
+        }
+        return parseClientStateModifiers(data, params);
+    }, [data, params]);
+    const serverUrl = getServersURL(data.servers, clientState ?? undefined);
+
+    return (
+        <OpenAPIContext.Provider
+            value={{
+                isPending,
+                state: clientState,
+                serverUrl,
+                onUpdate,
+            }}
+        >
+            {children}
+        </OpenAPIContext.Provider>
+    );
+}
+
+function parseClientStateModifiers(data: OpenAPIOperationData, params: Record<string, string>) {
+    if (!data) {
+        return null;
+    }
+    const serverQueryParam = params['server'];
+    const serverIndex =
+        serverQueryParam && !isNaN(Number(serverQueryParam))
+            ? Math.max(0, Math.min(Number(serverQueryParam), data.servers.length - 1))
+            : 0;
+    const server = data.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/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>

packages/react-openapi/src/OpenAPIServerURL.tsx

@@ -1,18 +1,30 @@
+'use client';
+
 import * as React from 'react';
 import { OpenAPIV3 } from 'openapi-types';
 import { OpenAPIServerURLVariable } from './OpenAPIServerURLVariable';
+import { OpenAPIClientContext } from './types';
+import { ServerURLForm } from './OpenAPIServerURLForm';
+import { useOpenAPIContext } from './OpenAPIContextProvider';
+import { parseServerURL } from './utils';
 
 /**
  * Show the url of the server with variables replaced by their default values.
  */
-export function OpenAPIServerURL(props: { servers: OpenAPIV3.ServerObject[] }) {
-    const { servers } = props;
-    const server = servers[0];
+export function OpenAPIServerURL(props: {
+    servers: OpenAPIV3.ServerObject[];
+    context: OpenAPIClientContext;
+    path?: string;
+}) {
+    const { path, servers, context } = props;
+    const ctx = useOpenAPIContext();
 
+    const serverIndex = !isNaN(Number(ctx?.state?.server)) ? Number(ctx?.state?.server) : 0;
+    const server = servers[serverIndex];
     const parts = parseServerURL(server?.url ?? '');
 
     return (
-        <span>
+        <ServerURLForm context={context} servers={servers} serverIndex={serverIndex}>
             {parts.map((part, i) => {
                 if (part.kind === 'text') {
                     return <span key={i}>{part.text}</span>;
@@ -26,41 +38,13 @@ export function OpenAPIServerURL(props: { servers: OpenAPIV3.ServerObject[] }) {
                             key={i}
                             name={part.name}
                             variable={server.variables[part.name]}
+                            selectionIndex={Number(ctx?.state?.[part.name])}
+                            selectable={Boolean(ctx?.state?.edit)}
                         />
                     );
                 }
             })}
-        </span>
+            {path}
+        </ServerURLForm>
     );
 }
-
-/**
- * Get the default URL for the server.
- */
-export function getServersURL(servers: OpenAPIV3.ServerObject[]): string {
-    const server = servers[0];
-    const parts = parseServerURL(server?.url ?? '');
-
-    return parts
-        .map((part) => {
-            if (part.kind === 'text') {
-                return part.text;
-            } else {
-                return server.variables?.[part.name]?.default ?? `{${part.name}}`;
-            }
-        })
-        .join('');
-}
-
-function parseServerURL(url: string) {
-    const parts = url.split(/{([^}]+)}/g);
-    const result: Array<{ kind: 'variable'; name: string } | { kind: 'text'; text: string }> = [];
-    for (let i = 0; i < parts.length; i++) {
-        if (i % 2 === 0) {
-            result.push({ kind: 'text', text: parts[i] });
-        } else {
-            result.push({ kind: 'variable', name: parts[i] });
-        }
-    }
-    return result;
-}