set x-state

elastic · Oct 17, 2024 · 58d13de · 58d13de
1 parent 60be4e4
commit 58d13de
Show file tree

Hide file tree

Showing 4 changed files with 29 additions and 2 deletions.
diff --git a/packages/kbn-router-to-openapispec/src/process_router.ts b/packages/kbn-router-to-openapispec/src/process_router.ts
@@ -23,9 +23,11 @@ import {
   getVersionedHeaderParam,
   mergeResponseContent,
   prepareRoutes,
+  setXState,
 } from './util';
 import type { OperationIdCounter } from './operation_id_counter';
 import type { GenerateOpenApiDocumentOptionsFilters } from './generate_oas';
+import type { CustomOperationObject } from './type';
 
 export const processRouter = (
   appRouter: Router,
@@ -61,7 +63,7 @@ export const processRouter = (
         parameters.push(...pathObjects, ...queryObjects);
       }
 
-      const operation: OpenAPIV3.OperationObject = {
+      const operation: CustomOperationObject = {
         summary: route.options.summary ?? '',
         tags: route.options.tags ? extractTags(route.options.tags) : [],
         ...(route.options.description ? { description: route.options.description } : {}),
@@ -81,6 +83,8 @@ export const processRouter = (
         operationId: getOpId(route.path),
       };
 
+      setXState(route.options.availability, operation);
+
       const path: OpenAPIV3.PathItemObject = {
         [route.method]: operation,
       };

diff --git a/packages/kbn-router-to-openapispec/src/process_versioned_router.ts b/packages/kbn-router-to-openapispec/src/process_versioned_router.ts
@@ -29,6 +29,7 @@ import {
   extractTags,
   mergeResponseContent,
   getXsrfHeaderForMethod,
+  setXState,
 } from './util';
 
 export const processVersionedRouter = (
@@ -112,6 +113,9 @@ export const processVersionedRouter = (
         parameters,
         operationId: getOpId(route.path),
       };
+
+      setXState(route.options.options?.availability, operation);
+
       const path: OpenAPIV3.PathItemObject = {
         [route.method]: operation,
       };

diff --git a/packages/kbn-router-to-openapispec/src/type.ts b/packages/kbn-router-to-openapispec/src/type.ts
@@ -34,3 +34,8 @@ export interface OpenAPIConverter {
 
   is(type: unknown): boolean;
 }
+
+export type CustomOperationObject = OpenAPIV3.OperationObject<{
+  // Custom OpenAPI from ES API spec based on @availability
+  'x-state'?: 'Technical Preview' | 'Beta';
+}>;
diff --git a/packages/kbn-router-to-openapispec/src/util.ts b/packages/kbn-router-to-openapispec/src/util.ts
@@ -17,7 +17,7 @@ import {
   type RouterRoute,
   type RouteValidatorConfig,
 } from '@kbn/core-http-server';
-import { KnownParameters } from './type';
+import { CustomOperationObject, KnownParameters } from './type';
 import type { GenerateOpenApiDocumentOptionsFilters } from './generate_oas';
 
 const tagPrefix = 'oas-tag:';
@@ -165,3 +165,17 @@ export const getXsrfHeaderForMethod = (
     },
   ];
 };
+
+export function setXState(
+  availability: RouteConfigOptions<RouteMethod>['availability'],
+  operation: CustomOperationObject
+): void {
+  if (availability) {
+    if (availability.stability === 'experimental') {
+      operation['x-state'] = 'Technical Preview';
+    }
+    if (availability.stability === 'beta') {
+      operation['x-state'] = 'Beta';
+    }
+  }
+}