feat(api): Badge experimental endpoints on API reference pages

src/build/open-api/types.ts

@@ -72,6 +72,7 @@ export type DeRefedOpenAPI = {
         description?: string;
         security?: any;
         servers?: ServerMeta[];
+        'x-sentry-experimental'?: boolean;
       };
     };
   };

src/build/resolveOpenAPI.ts

@@ -64,6 +64,7 @@ export type API = {
   apiPath: string;
   bodyParameters: APIParameter[];
   deprecated: boolean;
+  experimental: boolean;
   method: string;
   name: string;
   pathParameters: APIParameter[];
@@ -97,6 +98,11 @@ function slugify(s: string): string {
 
 const DEPRECATED_PREFIX_REGEX = /^\(DEPRECATED\)\s*/;
 
+// Sentry prepends this notice to the description of every experimental operation, so
+// that consumers with no badge of their own still warn the reader. We render a badge,
+// so strip it rather than saying the same thing twice.
+const EXPERIMENTAL_NOTICE_REGEX = /^\*\*Experimental:\*\*[^\n]*\n+/;
+
 function isDeprecatedOperationId(operationId: string | undefined): boolean {
   return operationId ? DEPRECATED_PREFIX_REGEX.test(operationId) : false;
 }
@@ -135,6 +141,7 @@ async function apiCategoriesUncached(): Promise<APICategory[]> {
       const isDeprecated =
         isDeprecatedOperationId(apiData.operationId) ||
         isDeprecatedOperationId(apiData.summary);
+      const isExperimental = apiData['x-sentry-experimental'] === true;
       const titleSource = apiData.summary || apiData.operationId || '';
       const cleanName = stripDeprecatedPrefix(titleSource);
 
@@ -148,12 +155,15 @@ async function apiCategoriesUncached(): Promise<APICategory[]> {
           method,
           name: cleanName,
           deprecated: isDeprecated,
+          experimental: isExperimental,
           server,
           slug: slugify(cleanName),
           summary: apiData.summary
             ? stripDeprecatedPrefix(apiData.summary)
             : apiData.summary,
-          descriptionMarkdown: apiData.description,
+          descriptionMarkdown: isExperimental
+            ? apiData.description?.replace(EXPERIMENTAL_NOTICE_REGEX, '')
+            : apiData.description,
           pathParameters: (apiData.parameters || []).filter(
             p => p.in === 'path'
           ) as APIParameter[],

src/components/apiPage/index.tsx

@@ -125,6 +125,16 @@ export function ApiPage({api}: Props) {
   };
   return (
     <DocPage frontMatter={frontMatter} notoc fullWidth>
+      {api.experimental && (
+        <div className="flex items-center gap-2 mb-4">
+          <span className="text-xs font-medium px-2 py-0.5 rounded bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-200">
+            Experimental
+          </span>
+          <span className="text-sm text-gray-600 dark:text-gray-300">
+            This API is under active development and may change.
+          </span>
+        </div>
+      )}
       <div className="flex">
         <div className="w-full">
           <div className="api-block">