Render OpenAPISchemas block (#2959)

Author: nolannbiron

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

@@ -25,7 +25,7 @@ import { IntegrationBlock } from './Integration';
 import { List } from './List';
 import { ListItem } from './ListItem';
 import { BlockMath } from './Math';
-import { OpenAPI } from './OpenAPI';
+import { OpenAPIOperation, OpenAPISchemas } from './OpenAPI';
 import { Paragraph } from './Paragraph';
 import { Quote } from './Quote';
 import { ReusableContent } from './ReusableContent';
@@ -82,9 +82,9 @@ export function Block<T extends DocumentBlock>(props: BlockProps<T>) {
                 return <Table {...props} block={block} />;
             case 'swagger':
             case 'openapi-operation':
-                return <OpenAPI {...props} block={block} />;
+                return <OpenAPIOperation {...props} block={block} />;
             case 'openapi-schemas':
-                return <></>;
+                return <OpenAPISchemas {...props} block={block} />;
             case 'embed':
                 return <Embed {...props} block={block} />;
             case 'blockquote':

packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPI.tsx renamed to packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPIOperation.tsx

@@ -1,6 +1,6 @@
 import type { JSONDocument } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
-import { OpenAPIOperation } from '@gitbook/react-openapi';
+import { OpenAPIOperation as BaseOpenAPIOperation } from '@gitbook/react-openapi';
 
 import { resolveOpenAPIOperationBlock } from '@/lib/openapi/resolveOpenAPIOperationBlock';
 import { tcls } from '@/lib/tailwind';
@@ -12,21 +12,21 @@ import { Heading } from '../Heading';
 
 import './scalar.css';
 import './style.css';
-import type { AnyOpenAPIBlock } from '@/lib/openapi/types';
+import type { AnyOpenAPIOperationsBlock } from '@/lib/openapi/types';
 
 /**
  * Render an openapi block or an openapi-operation block.
  */
-export async function OpenAPI(props: BlockProps<AnyOpenAPIBlock>) {
+export async function OpenAPIOperation(props: BlockProps<AnyOpenAPIOperationsBlock>) {
     const { style } = props;
     return (
         <div className={tcls('flex w-full', style, 'max-w-full')}>
-            <OpenAPIBody {...props} />
+            <OpenAPIOperationBody {...props} />
         </div>
     );
 }
 
-async function OpenAPIBody(props: BlockProps<AnyOpenAPIBlock>) {
+async function OpenAPIOperationBody(props: BlockProps<AnyOpenAPIOperationsBlock>) {
     const { block, context } = props;
 
     if (!context.contentContext) {
@@ -53,7 +53,7 @@ async function OpenAPIBody(props: BlockProps<AnyOpenAPIBlock>) {
     }
 
     return (
-        <OpenAPIOperation
+        <BaseOpenAPIOperation
             data={data}
             context={{
                 specUrl,

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

@@ -0,0 +1,67 @@
+import { resolveOpenAPISchemasBlock } from '@/lib/openapi/resolveOpenAPISchemasBlock';
+import { tcls } from '@/lib/tailwind';
+import { Icon } from '@gitbook/icons';
+import { OpenAPISchemas as BaseOpenAPISchemas } from '@gitbook/react-openapi';
+
+import type { BlockProps } from '../Block';
+
+import './scalar.css';
+import './style.css';
+import type { OpenAPISchemasBlock } from '@/lib/openapi/types';
+
+/**
+ * Render an openapi-schemas block.
+ */
+export async function OpenAPISchemas(props: BlockProps<OpenAPISchemasBlock>) {
+    const { style } = props;
+    return (
+        <div className={tcls('flex w-full', style, 'max-w-full')}>
+            <OpenAPISchemasBody {...props} />
+        </div>
+    );
+}
+
+async function OpenAPISchemasBody(props: BlockProps<OpenAPISchemasBlock>) {
+    const { block, context } = props;
+
+    if (!context.contentContext) {
+        return null;
+    }
+
+    const { data, specUrl, error } = await resolveOpenAPISchemasBlock({
+        block,
+        context: context.contentContext,
+    });
+
+    if (error) {
+        return (
+            <div className="hidden">
+                <p>
+                    Error with {specUrl}: {error.message}
+                </p>
+            </div>
+        );
+    }
+
+    if (!data || !specUrl) {
+        return null;
+    }
+
+    return (
+        <BaseOpenAPISchemas
+            data={data}
+            context={{
+                specUrl,
+                icons: {
+                    chevronDown: <Icon icon="chevron-down" />,
+                    chevronRight: <Icon icon="chevron-right" />,
+                    plus: <Icon icon="plus" />,
+                },
+                defaultInteractiveOpened: context.mode === 'print',
+                id: block.meta?.id,
+                blockKey: block.key,
+            }}
+            className="openapi-block"
+        />
+    );
+}

packages/gitbook/src/components/DocumentView/OpenAPI/index.ts

@@ -1 +1,2 @@
-export * from './OpenAPI';
+export * from './OpenAPIOperation';
+export * from './OpenAPISchemas';

packages/gitbook/src/lib/openapi/fetch.ts

@@ -1,18 +1,24 @@
 import { parseOpenAPI } from '@gitbook/openapi-parser';
 
 import { type CacheFunctionOptions, cache, noCacheFetchOptions } from '@/lib/cache';
-import type { ResolveOpenAPIBlockArgs } from '@/lib/openapi/types';
+import type {
+    AnyOpenAPIOperationsBlock,
+    OpenAPISchemasBlock,
+    ResolveOpenAPIBlockArgs,
+} from '@/lib/openapi/types';
 import { assert } from 'ts-essentials';
 import { resolveContentRef } from '../references';
 import { isV2 } from '../v2';
 import { enrichFilesystem } from './enrich';
 import type { FetchOpenAPIFilesystemResult } from './types';
 
+type AnyOpenAPIBlock = AnyOpenAPIOperationsBlock | OpenAPISchemasBlock;
+
 /**
  * Fetch OpenAPI block.
  */
 export async function fetchOpenAPIFilesystem(
-    args: ResolveOpenAPIBlockArgs
+    args: ResolveOpenAPIBlockArgs<AnyOpenAPIBlock>
 ): Promise<FetchOpenAPIFilesystemResult> {
     const { context, block } = args;
 

packages/gitbook/src/lib/openapi/resolveOpenAPIOperationBlock.ts

@@ -1,18 +1,25 @@
 import { fetchOpenAPIFilesystem } from '@/lib/openapi/fetch';
 import { OpenAPIParseError } from '@gitbook/openapi-parser';
 import { type OpenAPIOperationData, resolveOpenAPIOperation } from '@gitbook/react-openapi';
-import type { AnyOpenAPIBlock, ResolveOpenAPIBlockArgs, ResolveOpenAPIBlockResult } from './types';
+import type {
+    AnyOpenAPIOperationsBlock,
+    ResolveOpenAPIBlockArgs,
+    ResolveOpenAPIBlockResult,
+} from './types';
 
 type ResolveOpenAPIOperationBlockResult = ResolveOpenAPIBlockResult<OpenAPIOperationData>;
 
-const weakmap = new WeakMap<AnyOpenAPIBlock, Promise<ResolveOpenAPIOperationBlockResult>>();
+const weakmap = new WeakMap<
+    AnyOpenAPIOperationsBlock,
+    Promise<ResolveOpenAPIOperationBlockResult>
+>();
 
 /**
  * Cache the result of resolving an OpenAPI block.
  * It is important because the resolve is called in sections and in the block itself.
  */
 export function resolveOpenAPIOperationBlock(
-    args: ResolveOpenAPIBlockArgs
+    args: ResolveOpenAPIBlockArgs<AnyOpenAPIOperationsBlock>
 ): Promise<ResolveOpenAPIOperationBlockResult> {
     if (weakmap.has(args.block)) {
         return weakmap.get(args.block)!;
@@ -27,7 +34,7 @@ export function resolveOpenAPIOperationBlock(
  * Resolve OpenAPI operation block.
  */
 async function baseResolveOpenAPIOperationBlock(
-    args: ResolveOpenAPIBlockArgs
+    args: ResolveOpenAPIBlockArgs<AnyOpenAPIOperationsBlock>
 ): Promise<ResolveOpenAPIOperationBlockResult> {
     const { context, block } = args;
     if (!block.data.path || !block.data.method) {

packages/gitbook/src/lib/openapi/resolveOpenAPISchemasBlock.ts

@@ -1,19 +1,22 @@
-import { fetchOpenAPIFilesystem } from '@/lib/openapi/fetch';
-import type { ResolveOpenAPIBlockResult } from '@/lib/openapi/types';
 import { OpenAPIParseError } from '@gitbook/openapi-parser';
 import { type OpenAPISchemasData, resolveOpenAPISchemas } from '@gitbook/react-openapi';
-import type { AnyOpenAPIBlock, ResolveOpenAPIBlockArgs } from './types';
+import { fetchOpenAPIFilesystem } from './fetch';
+import type {
+    OpenAPISchemasBlock,
+    ResolveOpenAPIBlockArgs,
+    ResolveOpenAPIBlockResult,
+} from './types';
 
 type ResolveOpenAPISchemasBlockResult = ResolveOpenAPIBlockResult<OpenAPISchemasData>;
 
-const weakmap = new WeakMap<AnyOpenAPIBlock, Promise<ResolveOpenAPISchemasBlockResult>>();
+const weakmap = new WeakMap<OpenAPISchemasBlock, Promise<ResolveOpenAPISchemasBlockResult>>();
 
 /**
  * Cache the result of resolving an OpenAPI block.
  * It is important because the resolve is called in sections and in the block itself.
  */
 export function resolveOpenAPISchemasBlock(
-    args: ResolveOpenAPIBlockArgs
+    args: ResolveOpenAPIBlockArgs<OpenAPISchemasBlock>
 ): Promise<ResolveOpenAPISchemasBlockResult> {
     if (weakmap.has(args.block)) {
         return weakmap.get(args.block)!;
@@ -28,10 +31,10 @@ export function resolveOpenAPISchemasBlock(
  * Resolve OpenAPI schemas block.
  */
 async function baseResolveOpenAPISchemasBlock(
-    args: ResolveOpenAPIBlockArgs
+    args: ResolveOpenAPIBlockArgs<OpenAPISchemasBlock>
 ): Promise<ResolveOpenAPISchemasBlockResult> {
     const { context, block } = args;
-    if (!block.data.path || !block.data.method) {
+    if (!block.data.schemas || !block.data.schemas.length) {
         return { data: null, specUrl: null };
     }
 
@@ -42,7 +45,9 @@ async function baseResolveOpenAPISchemasBlock(
             return { data: null, specUrl: null };
         }
 
-        const data = await resolveOpenAPISchemas(filesystem);
+        const data = await resolveOpenAPISchemas(filesystem, {
+            schemas: block.data.schemas,
+        });
 
         return { data, specUrl };
     } catch (error) {

packages/gitbook/src/lib/openapi/types.ts

@@ -1,15 +1,26 @@
-import type { DocumentBlockOpenAPI, DocumentBlockOpenAPIOperation } from '@gitbook/api';
+import type {
+    DocumentBlockOpenAPI,
+    DocumentBlockOpenAPIOperation,
+    DocumentBlockOpenAPISchemas,
+} from '@gitbook/api';
 import type { Filesystem, OpenAPIParseError, OpenAPIV3xDocument } from '@gitbook/openapi-parser';
 import type { GitBookAnyContext } from '@v2/lib/context';
 
-//!!TODO: Add DocumentBlockOpenAPISchemas when available in @gitbook/api
-export type AnyOpenAPIBlock = DocumentBlockOpenAPI | DocumentBlockOpenAPIOperation;
+/**
+ * Type for both OpenAPI & OpenAPIOperation block
+ */
+export type AnyOpenAPIOperationsBlock = DocumentBlockOpenAPI | DocumentBlockOpenAPIOperation;
+
+/**
+ * Type for OpenAPI Schemas block
+ */
+export type OpenAPISchemasBlock = DocumentBlockOpenAPISchemas;
 
 /**
  * Arguments for resolving OpenAPI block.
  */
-export type ResolveOpenAPIBlockArgs = {
-    block: AnyOpenAPIBlock;
+export type ResolveOpenAPIBlockArgs<T> = {
+    block: T;
     context: GitBookAnyContext;
 };
 

packages/react-openapi/src/schemas/OpenAPISchemas.tsx

@@ -4,13 +4,18 @@ import { OpenAPIRootSchema } from '../OpenAPISchema';
 import { Section, SectionBody } from '../StaticSection';
 import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPISchemasData } from '../types';
 
+type OpenAPISchemasContextProps = Omit<
+    OpenAPIContextProps,
+    'renderCodeBlock' | 'renderHeading' | 'renderDocument'
+>;
+
 /**
  * Display OpenAPI Schemas.
  */
 export function OpenAPISchemas(props: {
     className?: string;
     data: OpenAPISchemasData;
-    context: OpenAPIContextProps;
+    context: OpenAPISchemasContextProps;
 }) {
     const { className, data, context } = props;
     const { schemas } = data;