From 5b1e01c78624a2d7e2c489cc322cfefbe6335dfd Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Mon, 31 Mar 2025 13:49:37 +0200
Subject: [PATCH] Support for x-stability property (#3064)

---
 .changeset/silly-mice-lie.md                  |  7 ++++
 .../DocumentView/OpenAPI/OpenAPIOperation.tsx |  7 +++-
 .../components/DocumentView/OpenAPI/style.css | 23 ++++++++++-
 packages/openapi-parser/src/types.ts          |  8 ++++
 .../react-openapi/src/OpenAPIOperation.tsx    | 41 ++++++++++++++++++-
 packages/react-openapi/src/types.ts           |  6 ++-
 6 files changed, 87 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/silly-mice-lie.md

diff --git a/.changeset/silly-mice-lie.md b/.changeset/silly-mice-lie.md
new file mode 100644
index 000000000..c8df5ddbe
--- /dev/null
+++ b/.changeset/silly-mice-lie.md
@@ -0,0 +1,7 @@
+---
+'@gitbook/openapi-parser': patch
+'@gitbook/react-openapi': patch
+'gitbook': patch
+---
+
+Support for x-stability property
diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPIOperation.tsx b/packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPIOperation.tsx
index 85aaef171..294dd876c 100644
--- a/packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPIOperation.tsx
+++ b/packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPIOperation.tsx
@@ -77,7 +77,12 @@ async function OpenAPIOperationBody(props: BlockProps<AnyOpenAPIOperationsBlock>
                         ancestorBlocks={props.ancestorBlocks}
                         isEstimatedOffscreen={props.isEstimatedOffscreen}
                         context={props.context}
-                        style={headingProps.deprecated ? 'line-through' : undefined}
+                        style={tcls([
+                            headingProps.deprecated ? 'line-through' : undefined,
+                            headingProps.deprecated || !!headingProps.stability
+                                ? '[&>div]:mt-0'
+                                : undefined,
+                        ])}
                         block={{
                             object: 'block',
                             key: `${block.key}-heading`,
diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
index 6051155af..c0bf8d13c 100644
--- a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
+++ b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
@@ -20,10 +20,31 @@
     @apply flex flex-col items-start justify-start gap-3;
 }
 
-.openapi-deprecated {
+.openapi-summary-tags {
+    @apply flex flex-row gap-2 mt-[0.75em];
+}
+
+.openapi-deprecated,
+.openapi-stability {
     @apply py-0.5 px-1.5 min-w-[1.625rem] font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint bg-tint rounded text-sm leading-[calc(max(1.20em,1.25rem))] before:!content-none after:!content-none;
 }
 
+.openapi-stability-stable {
+    @apply text-green-600 dark:text-green-300 bg-green-50 dark:bg-green-900/6 ring-green-500/5;
+}
+
+.openapi-stability-alpha {
+    @apply text-amber-700 dark:text-amber-300 bg-amber-50 dark:bg-amber-900/6 ring-amber-500/5;
+}
+
+.openapi-stability-beta {
+    @apply text-blue-700 dark:text-blue-300 bg-blue-50 dark:bg-blue-900/6 ring-blue-500/5;
+}
+
+.openapi-stability-experimental {
+    @apply text-violet-700 dark:text-violet-300 bg-violet-50 dark:bg-violet-900/6 ring-violet-500/5;
+}
+
 .openapi-deprecated-sunset-date {
     @apply font-semibold font-mono truncate;
 }
diff --git a/packages/openapi-parser/src/types.ts b/packages/openapi-parser/src/types.ts
index 3b55c21ab..6c72c284c 100644
--- a/packages/openapi-parser/src/types.ts
+++ b/packages/openapi-parser/src/types.ts
@@ -62,8 +62,16 @@ export interface OpenAPICustomOperationProperties {
             name?: string;
         };
     };
+
+    /**
+     * Stability of the operation.
+     * @enum 'experimental' | 'alpha' | 'beta' | 'stable'
+     */
+    'x-stability'?: OpenAPIStability;
 }
 
+export type OpenAPIStability = 'experimental' | 'alpha' | 'beta' | 'stable';
+
 /**
  * Custom code samples that can be defined at the operation level.
  * It follows the spec defined by Redocly.
diff --git a/packages/react-openapi/src/OpenAPIOperation.tsx b/packages/react-openapi/src/OpenAPIOperation.tsx
index 6c186f1a5..e5672c631 100644
--- a/packages/react-openapi/src/OpenAPIOperation.tsx
+++ b/packages/react-openapi/src/OpenAPIOperation.tsx
@@ -1,6 +1,10 @@
 import clsx from 'clsx';
 
-import type { OpenAPICustomOperationProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
+import type {
+    OpenAPICustomOperationProperties,
+    OpenAPIStability,
+    OpenAPIV3,
+} from '@gitbook/openapi-parser';
 import { Markdown } from './Markdown';
 import { OpenAPICodeSample } from './OpenAPICodeSample';
 import { OpenAPIPath } from './OpenAPIPath';
@@ -29,14 +33,24 @@ export function OpenAPIOperation(props: {
     return (
         <div className={clsx('openapi-operation', className)}>
             <div className="openapi-summary" id={operation.summary ? undefined : context.id}>
+                {(operation.deprecated || operation['x-stability']) && (
+                    <div className="openapi-summary-tags">
+                        {operation.deprecated && (
+                            <div className="openapi-deprecated">Deprecated</div>
+                        )}
+                        {operation['x-stability'] && (
+                            <OpenAPIOperationStability stability={operation['x-stability']} />
+                        )}
+                    </div>
+                )}
                 {operation.summary
                     ? context.renderHeading({
                           deprecated: operation.deprecated ?? false,
+                          stability: operation['x-stability'],
                           title: operation.summary,
                       })
                     : null}
                 <OpenAPIPath data={data} context={context} />
-                {operation.deprecated && <div className="openapi-deprecated">Deprecated</div>}
             </div>
             <div className="openapi-columns">
                 <div className="openapi-column-spec">
@@ -89,3 +103,26 @@ function OpenAPIOperationDescription(props: {
         </div>
     );
 }
+
+const stabilityEnum = {
+    experimental: 'Experimental',
+    alpha: 'Alpha',
+    beta: 'Beta',
+    stable: 'Stable',
+} as const;
+
+function OpenAPIOperationStability(props: { stability: OpenAPIStability }) {
+    const { stability } = props;
+
+    const foundStability = stabilityEnum[stability];
+
+    if (!foundStability) {
+        return null;
+    }
+
+    return (
+        <div className={`openapi-stability openapi-stability-${foundStability.toLowerCase()}`}>
+            {foundStability}
+        </div>
+    );
+}
diff --git a/packages/react-openapi/src/types.ts b/packages/react-openapi/src/types.ts
index 6557fb3e4..011b420f1 100644
--- a/packages/react-openapi/src/types.ts
+++ b/packages/react-openapi/src/types.ts
@@ -13,7 +13,11 @@ export interface OpenAPIContextProps extends OpenAPIClientContext {
     /**
      * Render the heading of the operation.
      */
-    renderHeading: (props: { deprecated: boolean; title: string }) => React.ReactNode;
+    renderHeading: (props: {
+        deprecated: boolean;
+        title: string;
+        stability?: string;
+    }) => React.ReactNode;
     /**
      * Render the document of the operation.
      */