Support OpenAPI operation block (#2902)

Author: gregberge

.changeset/tough-plums-bow.md

@@ -0,0 +1,5 @@
+---
+'gitbook': patch
+---
+
+Support OpenAPI operation block

bun.lock

@@ -40,7 +40,7 @@
       "name": "gitbook",
       "version": "0.6.3",
       "dependencies": {
-        "@gitbook/api": "^0.96.0",
+        "@gitbook/api": "0.96.1",
         "@gitbook/cache-do": "workspace:*",
         "@gitbook/colors": "workspace:*",
         "@gitbook/emoji-codepoints": "workspace:*",
@@ -120,7 +120,7 @@
       "name": "gitbook-v2",
       "version": "0.1.0",
       "dependencies": {
-        "@gitbook/api": "^0.96.0",
+        "@gitbook/api": "0.96.1",
         "@sindresorhus/fnv1a": "^3.1.0",
         "next": "canary",
         "react": "^19.0.0",
@@ -180,7 +180,7 @@
       "name": "@gitbook/react-contentkit",
       "version": "0.6.0",
       "dependencies": {
-        "@gitbook/api": "^0.96.0",
+        "@gitbook/api": "0.96.1",
         "assert-never": "^1.2.1",
         "classnames": "^2.5.1",
       },
@@ -604,7 +604,7 @@
 
     "@fortawesome/fontawesome-svg-core": ["@fortawesome/[email protected]", "", { "dependencies": { "@fortawesome/fontawesome-common-types": "6.6.0" } }, "sha512-KHwPkCk6oRT4HADE7smhfsKudt9N/9lm6EJ5BVg0tD1yPA5hht837fB87F8pn15D8JfTqQOjhKTktwmLMiD7Kg=="],
 
-    "@gitbook/api": ["@gitbook/[email protected].0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-JN6k0PlpyQQhtr8sNnbKIWQ7n9gCFqhrDo33v/41d41M1wgz+eowm1jdiYtX0tsXBH7D1YHmBMbNnDI8jQwbwA=="],
+    "@gitbook/api": ["@gitbook/[email protected].1", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-E1hpaFNFoEyc8E4rIQyC6UD3kErGXAI0lKt04zYQQYOBLjRIQ57D4oNIIJBjWn4hHeSxRxWvW3NcxzvOGMmIqQ=="],
 
     "@gitbook/cache-do": ["@gitbook/cache-do@workspace:packages/cache-do"],
 
@@ -4238,7 +4238,7 @@
 
     "gaxios/node-fetch": ["[email protected]", "", { "dependencies": { "whatwg-url": "^5.0.0" }, "peerDependencies": { "encoding": "^0.1.0" }, "optionalPeers": ["encoding"] }, "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A=="],
 
-    "gitbook-v2/next": ["[email protected]", "", { "dependencies": { "@next/env": "15.2.0-canary.74", "@swc/counter": "0.1.3", "@swc/helpers": "0.5.15", "busboy": "1.6.0", "caniuse-lite": "^1.0.30001579", "postcss": "8.4.31", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "15.2.0-canary.74", "@next/swc-darwin-x64": "15.2.0-canary.74", "@next/swc-linux-arm64-gnu": "15.2.0-canary.74", "@next/swc-linux-arm64-musl": "15.2.0-canary.74", "@next/swc-linux-x64-gnu": "15.2.0-canary.74", "@next/swc-linux-x64-musl": "15.2.0-canary.74", "@next/swc-win32-arm64-msvc": "15.2.0-canary.74", "@next/swc-win32-x64-msvc": "15.2.0-canary.74", "sharp": "^0.33.5" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.41.2", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-0BkYq0136wVKLogN0R85cnSKpnlSHg4/mA5lMWJGp/ltfai+vRaejWre1fhpjNVFuNOnzblFhpTQlwxZk/mN8g=="],
+    "gitbook-v2/next": ["[email protected]", "", { "dependencies": { "@next/env": "15.2.1-canary.2", "@swc/counter": "0.1.3", "@swc/helpers": "0.5.15", "busboy": "1.6.0", "caniuse-lite": "^1.0.30001579", "postcss": "8.4.31", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "15.2.1-canary.2", "@next/swc-darwin-x64": "15.2.1-canary.2", "@next/swc-linux-arm64-gnu": "15.2.1-canary.2", "@next/swc-linux-arm64-musl": "15.2.1-canary.2", "@next/swc-linux-x64-gnu": "15.2.1-canary.2", "@next/swc-linux-x64-musl": "15.2.1-canary.2", "@next/swc-win32-arm64-msvc": "15.2.1-canary.2", "@next/swc-win32-x64-msvc": "15.2.1-canary.2", "sharp": "^0.33.5" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.41.2", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-Vrl8pSN3I7fuUWYWSqbzRsItKYm0X0OXPwm6/DuX7Pgi6uyYT6uwpvEGiPHSGV5Up1MOOtlsCjIbEQlNJ3t1pg=="],
 
     "google-auth-library/jws": ["[email protected]", "", { "dependencies": { "jwa": "^2.0.0", "safe-buffer": "^5.0.1" } }, "sha512-KDncfTmOZoOMTFG4mBlG0qUIOlc03fmzH+ru6RgYVZhPkyiy/92Owlt/8UEN+a4TXR1FQetfIpJE8ApdvdVxTg=="],
 
@@ -5138,23 +5138,23 @@
 
     "gaxios/https-proxy-agent/debug": ["[email protected]", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-Er2nc/H7RrMXZBFCEim6TCmMk02Z8vLC2Rbi1KEBggpo0fS6l0S1nnapwmIi3yW/+GOJap1Krg4w0Hg80oCqgQ=="],
 
-    "gitbook-v2/next/@next/env": ["@next/[email protected].0-canary.74", "", {}, "sha512-REBWD6TnX8M89GsvyuGJCziV2SJOPOZJjuo2y+uN8qlBmVnJQ9qk4tGTRqTygnQREfiKXjumncsGG0xZaWGZbw=="],
+    "gitbook-v2/next/@next/env": ["@next/[email protected].1-canary.2", "", {}, "sha512-8bs9W8rN9ln19PA3IdglEkuRxNI+VAjY/Gxkkp24qpSO19uKHbORFz3I5DGyRzHzTRDpCRGHQDKNbcy2b0buOQ=="],
 
-    "gitbook-v2/next/@next/swc-darwin-arm64": ["@next/[email protected].0-canary.74", "", { "os": "darwin", "cpu": "arm64" }, "sha512-R5pdSU94H9LSHXtDpvUWwKWL9p9xYlizenImZ7V1AAqbhiksBfORZHoHLZg6M0I+Ko6PTH2g6vPEAnKMYsH/xA=="],
+    "gitbook-v2/next/@next/swc-darwin-arm64": ["@next/[email protected].1-canary.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-PvoxT5tucaeREa7uhTxEaSW9sL4Sr8WfluVfSS+bj2axZpQ567gB/I+Eias67FPRW80cZaPMGsorNjyaq+cJuA=="],
 
-    "gitbook-v2/next/@next/swc-darwin-x64": ["@next/[email protected].0-canary.74", "", { "os": "darwin", "cpu": "x64" }, "sha512-2goUXrPl8iYEuS1JGzO17kmF+OTj7cCWX8nL/s/XpFC/iUJoWdcmWohaKP+DvKnS4SlYDdpSt733WaKGTwzvpw=="],
+    "gitbook-v2/next/@next/swc-darwin-x64": ["@next/[email protected].1-canary.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-tPg9F3bT5MMalZpLfd+paiWWaWLvUaWAFZfIGEBgozYgIBd66pROkb+dXsJVd73IlYoBDh3mYcK7me2uYImBOA=="],
 
-    "gitbook-v2/next/@next/swc-linux-arm64-gnu": ["@next/[email protected].0-canary.74", "", { "os": "linux", "cpu": "arm64" }, "sha512-FoulYpMof4m6LZJ5DR1agKQ0p0DyfX9ylo5CTzvFNfLmKkYmQWGaxG1KKv4YYaivhgYJ6GgubhXExJo/pycZQQ=="],
+    "gitbook-v2/next/@next/swc-linux-arm64-gnu": ["@next/[email protected].1-canary.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-LmnZN/psunvUXofINdGENFNDv7yRIET2szi2FREMr1epKL3NsAQD0k4hv3pwRLwkVb8z6Rj+TXzX0pFChHOlhg=="],
 
-    "gitbook-v2/next/@next/swc-linux-arm64-musl": ["@next/[email protected].0-canary.74", "", { "os": "linux", "cpu": "arm64" }, "sha512-gnmoPYieUhFysvzSVAbp83Z0n6MmPf1FsD300EA0OGsdhGcObRP/bPafporanU0XCHt44IgyA5KHwKIAoM3D3A=="],
+    "gitbook-v2/next/@next/swc-linux-arm64-musl": ["@next/[email protected].1-canary.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-5Ma1ATOCdgei1LRAbziBYciunyuG0uUASoiz7DDw40Ox5YuDD4Tznbg3re5ltWRwMAl9NNQa8ns3u+Q3Zs1NsQ=="],
 
-    "gitbook-v2/next/@next/swc-linux-x64-gnu": ["@next/[email protected].0-canary.74", "", { "os": "linux", "cpu": "x64" }, "sha512-pdkOOtywXSeGvdLr1xYHTSOa4O7zFJ1z79nvCnKCyeO690L5wtc6gxt5Kqjc6/FdDuhxRxCMVE3bEYdLmOGH1w=="],
+    "gitbook-v2/next/@next/swc-linux-x64-gnu": ["@next/[email protected].1-canary.2", "", { "os": "linux", "cpu": "x64" }, "sha512-R8bbqvKkVtzjN/KWogQQvWXgBTyWXcOEVgiPMXKgx7/zfybWeL+WjSXeepw4xYyDlQ1vC//HwEqLfFX41Jht4Q=="],
 
-    "gitbook-v2/next/@next/swc-linux-x64-musl": ["@next/[email protected].0-canary.74", "", { "os": "linux", "cpu": "x64" }, "sha512-WjleLpUuSYHiX8/fezvIWDBnNCmLjxypWloWaTunGy13A492CM+FjHbjmSNljDwI7LwT71jTZnc7+vM9uHz9Sg=="],
+    "gitbook-v2/next/@next/swc-linux-x64-musl": ["@next/[email protected].1-canary.2", "", { "os": "linux", "cpu": "x64" }, "sha512-wWr41f7g3H5FcLguoAS7bvqSqaVkhK97/fk7ANG1l5yW13F9qVPboVZvgVFrRsPFZgqANxs4AmhKAjjjT+mL1g=="],
 
-    "gitbook-v2/next/@next/swc-win32-arm64-msvc": ["@next/[email protected].0-canary.74", "", { "os": "win32", "cpu": "arm64" }, "sha512-E7G6Tj9VB09aog/7SeV3WbFdSrDRDaHeV6gtgHc5OuLpP37FwRVgFzBzL4u2MsOxqAkIw0Iq+SMPmagQLWrAWg=="],
+    "gitbook-v2/next/@next/swc-win32-arm64-msvc": ["@next/[email protected].1-canary.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-ogzvioGSaJ9F2VWZXiLQR4K4G6fbBUdlZfKowOJyFKfBhPK+WuwJlEnzWfPAe5YjtiQU2H+eMdZdC25DXDXo6g=="],
 
-    "gitbook-v2/next/@next/swc-win32-x64-msvc": ["@next/[email protected].0-canary.74", "", { "os": "win32", "cpu": "x64" }, "sha512-VipdINDvcGUpl6XwyhlwIoa3FBLFoMa1+EMyBDBySIH2Teq6HIy6Rqec5AfqDHbf3EKqRNTLx8tWum20cK6tXQ=="],
+    "gitbook-v2/next/@next/swc-win32-x64-msvc": ["@next/[email protected].1-canary.2", "", { "os": "win32", "cpu": "x64" }, "sha512-6sss7xGWck4DrJC7h/Gc2LFN3xh2dxnXxYmkxOD9gOq/yFdX7NSrNdCfNvXg5+6EFcTPURRg9gS9VgkzOCxp8Q=="],
 
     "gitbook-v2/next/postcss": ["[email protected]", "", { "dependencies": { "nanoid": "^3.3.6", "picocolors": "^1.0.0", "source-map-js": "^1.0.2" } }, "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ=="],
 

packages/gitbook-v2/package.json

@@ -6,7 +6,7 @@
         "next": "canary",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
-        "@gitbook/api": "^0.96.0",
+        "@gitbook/api": "0.96.1",
         "@sindresorhus/fnv1a": "^3.1.0",
         "server-only": "^0.0.1"
     },

packages/gitbook/package.json

@@ -16,7 +16,7 @@
         "clean": "rm -rf ./.next && rm -rf ./public/~gitbook/static/icons && rm -rf ./public/~gitbook/static/math"
     },
     "dependencies": {
-        "@gitbook/api": "^0.96.0",
+        "@gitbook/api": "0.96.1",
         "@gitbook/cache-do": "workspace:*",
         "@gitbook/colors": "workspace:*",
         "@gitbook/emoji-codepoints": "workspace:*",

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

@@ -81,6 +81,7 @@ export function Block<T extends DocumentBlock>(props: BlockProps<T>) {
             case 'table':
                 return <Table {...props} block={block} />;
             case 'swagger':
+            case 'openapi-operation':
                 return <OpenAPI {...props} block={block} />;
             case 'embed':
                 return <Embed {...props} block={block} />;
@@ -154,6 +155,7 @@ export function BlockSkeleton(props: { block: DocumentBlock; style: ClassValue }
         case 'expandable':
         case 'table':
         case 'swagger':
+        case 'openapi-operation':
         case 'math':
         case 'divider':
         case 'content-ref':

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

@@ -1,31 +1,31 @@
-import type { DocumentBlockOpenAPI, JSONDocument } from '@gitbook/api';
+import type { JSONDocument } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
 import { OpenAPIOperation } from '@gitbook/react-openapi';
 
-import { resolveOpenAPIBlock } from '@/lib/openapi/fetch';
+import { type AnyOpenAPIOperationBlock, resolveOpenAPIBlock } from '@/lib/openapi/fetch';
 import { tcls } from '@/lib/tailwind';
 
 import type { BlockProps } from '../Block';
 import { PlainCodeBlock } from '../CodeBlock';
 import { DocumentView } from '../DocumentView';
 import { Heading } from '../Heading';
 
-import './style.css';
 import './scalar.css';
+import './style.css';
 
 /**
- * Render an OpenAPI block.
+ * Render an openapi block or an openapi-operation block.
  */
-export async function OpenAPI(props: BlockProps<DocumentBlockOpenAPI>) {
+export async function OpenAPI(props: BlockProps<AnyOpenAPIOperationBlock>) {
     const { style } = props;
     return (
-        <div className={tcls('w-full', 'flex', 'flex-row', style, 'max-w-full')}>
+        <div className={tcls('flex w-full', style, 'max-w-full')}>
             <OpenAPIBody {...props} />
         </div>
     );
 }
 
-async function OpenAPIBody(props: BlockProps<DocumentBlockOpenAPI>) {
+async function OpenAPIBody(props: BlockProps<AnyOpenAPIOperationBlock>) {
     const { block, context } = props;
 
     if (!context.contentContext) {

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

@@ -1,21 +1,26 @@
-import type { DocumentBlockOpenAPI } from '@gitbook/api';
+import type { DocumentBlockOpenAPI, DocumentBlockOpenAPIOperation } from '@gitbook/api';
 import { OpenAPIParseError, parseOpenAPI } from '@gitbook/openapi-parser';
 import { type OpenAPIOperationData, resolveOpenAPIOperation } from '@gitbook/react-openapi';
 import type { GitBookAnyContext } from '@v2/lib/context';
 
 import { type CacheFunctionOptions, cache, noCacheFetchOptions } from '@/lib/cache';
 
+import { assert } from 'ts-essentials';
 import { resolveContentRef } from '../references';
 import { isV2 } from '../v2';
 import { enrichFilesystem } from './enrich';
 
-const weakmap = new WeakMap<DocumentBlockOpenAPI, ResolveOpenAPIBlockResult>();
+export type AnyOpenAPIOperationBlock = DocumentBlockOpenAPI | DocumentBlockOpenAPIOperation;
+
+const weakmap = new WeakMap<AnyOpenAPIOperationBlock, Promise<ResolveOpenAPIBlockResult>>();
 
 /**
  * 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 resolveOpenAPIBlock(args: ResolveOpenAPIBlockArgs): ResolveOpenAPIBlockResult {
+export function resolveOpenAPIBlock(
+    args: ResolveOpenAPIBlockArgs
+): Promise<ResolveOpenAPIBlockResult> {
     if (weakmap.has(args.block)) {
         return weakmap.get(args.block)!;
     }
@@ -26,30 +31,38 @@ export function resolveOpenAPIBlock(args: ResolveOpenAPIBlockArgs): ResolveOpenA
 }
 
 type ResolveOpenAPIBlockArgs = {
-    block: DocumentBlockOpenAPI;
+    block: AnyOpenAPIOperationBlock;
     context: GitBookAnyContext;
 };
-type ResolveOpenAPIBlockResult = Promise<
+export type ResolveOpenAPIBlockResult =
     | { error?: undefined; data: OpenAPIOperationData | null; specUrl: string | null }
-    | { error: OpenAPIParseError; data?: undefined; specUrl?: undefined }
->;
+    | { error: OpenAPIParseError; data?: undefined; specUrl?: undefined };
 /**
  * Resolve OpenAPI block.
  */
-async function baseResolveOpenAPIBlock(args: ResolveOpenAPIBlockArgs): ResolveOpenAPIBlockResult {
+async function baseResolveOpenAPIBlock(
+    args: ResolveOpenAPIBlockArgs
+): Promise<ResolveOpenAPIBlockResult> {
     const { context, block } = args;
     if (!block.data.path || !block.data.method) {
         return { data: null, specUrl: null };
     }
 
-    const resolved = block.data.ref ? await resolveContentRef(block.data.ref, context) : null;
+    const ref = block.data.ref;
+    const resolved = ref ? await resolveContentRef(ref, context) : null;
 
     if (!resolved) {
         return { data: null, specUrl: null };
     }
 
     try {
-        const filesystem = resolved.openAPIFilesystem ?? (await fetchFilesystem(resolved.href));
+        const filesystem = await (() => {
+            if (ref.kind === 'openapi') {
+                assert(resolved.openAPIFilesystem);
+                return resolved.openAPIFilesystem;
+            }
+            return fetchFilesystem(resolved.href);
+        })();
 
         const data = await resolveOpenAPIOperation(filesystem, {
             path: block.data.path,

packages/react-contentkit/package.json

@@ -10,7 +10,7 @@
     },
     "dependencies": {
         "classnames": "^2.5.1",
-        "@gitbook/api": "^0.96.0",
+        "@gitbook/api": "0.96.1",
         "assert-never": "^1.2.1"
     },
     "peerDependencies": {