[OAS] Update x-state behaviour to include availability.since (#221137)

## Summary

Updated the behaviour of `setXState` per
#221056.

Partially addresses that issue. In future we need to migrate existing
routes to add that information, this covers the Core provided
capability.


### Checklist


- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios

---------

Co-authored-by: kibanamachine <[email protected]>

Author: jloleysens

oas_docs/bundle.json

@@ -5430,7 +5430,8 @@
         "summary": "Schedule a snooze for the rule",
         "tags": [
           "alerting"
-        ]
+        ],
+        "x-state": "Generally available; added in 8.19.0"
       }
     },
     "/api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId}": {
@@ -5483,7 +5484,8 @@
         "summary": "Delete a snooze schedule for a rule",
         "tags": [
           "alerting"
-        ]
+        ],
+        "x-state": "Generally available; added in 8.19.0"
       }
     },
     "/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute": {

oas_docs/bundle.serverless.json

@@ -5430,7 +5430,8 @@
         "summary": "Schedule a snooze for the rule",
         "tags": [
           "alerting"
-        ]
+        ],
+        "x-state": "Generally available; added in 8.19.0"
       }
     },
     "/api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId}": {
@@ -5483,7 +5484,8 @@
         "summary": "Delete a snooze schedule for a rule",
         "tags": [
           "alerting"
-        ]
+        ],
+        "x-state": "Generally available; added in 8.19.0"
       }
     },
     "/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute": {

oas_docs/output/kibana.serverless.yaml

@@ -4219,6 +4219,7 @@ paths:
       summary: Schedule a snooze for the rule
       tags:
         - alerting
+      x-state: Generally available; added in 8.19.0
   /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute:
     post:
       operationId: post-alerting-rule-rule-id-alert-alert-id-mute
@@ -4324,6 +4325,7 @@ paths:
       summary: Delete a snooze schedule for a rule
       tags:
         - alerting
+      x-state: Generally available; added in 8.19.0
   /api/alerting/rules/_find:
     get:
       operationId: get-alerting-rules-find

oas_docs/output/kibana.yaml

@@ -4613,6 +4613,7 @@ paths:
       summary: Schedule a snooze for the rule
       tags:
         - alerting
+      x-state: Generally available; added in 8.19.0
   /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute:
     post:
       operationId: post-alerting-rule-rule-id-alert-alert-id-mute
@@ -4718,6 +4719,7 @@ paths:
       summary: Delete a snooze schedule for a rule
       tags:
         - alerting
+      x-state: Generally available; added in 8.19.0
   /api/alerting/rules/_find:
     get:
       operationId: get-alerting-rules-find

src/platform/packages/shared/kbn-router-to-openapispec/src/generate_oas.test.ts

@@ -10,7 +10,12 @@
 import { schema, Type } from '@kbn/config-schema';
 import { get } from 'lodash';
 import { generateOpenApiDocument } from './generate_oas';
-import { createTestRouters, createRouter, createVersionedRouter } from './generate_oas.test.util';
+import {
+  createTestRouters,
+  createRouter,
+  createVersionedRouter,
+  CreateTestRouterArgs,
+} from './generate_oas.test.util';
 import {
   sharedOas,
   createSharedZodSchema,
@@ -380,129 +385,206 @@ describe('generateOpenApiDocument', () => {
   });
 
   describe('availability', () => {
-    it('creates the expected availability entries', async () => {
-      const [routers, versionedRouters] = createTestRouters({
-        routers: {
-          testRouter1: {
-            routes: [
-              {
-                path: '/1-1/{id}/{path*}',
-                options: { availability: { stability: 'experimental' }, access: 'public' },
-              },
-              {
-                path: '/1-2/{id}/{path*}',
-                options: { availability: { stability: 'beta' }, access: 'public' },
-              },
-              {
-                path: '/1-3/{id}/{path*}',
-                options: { availability: { stability: 'stable' }, access: 'public' },
-              },
-            ],
+    const testCases = [
+      {
+        name: 'router with experimental stability',
+        routerConfig: {
+          routers: {
+            testRouter: {
+              routes: [
+                {
+                  path: '/test-path/{id}/{path*}',
+                  options: { availability: { stability: 'experimental' }, access: 'public' },
+                },
+              ],
+            },
           },
-          testRouter2: {
-            routes: [{ path: '/2-1/{id}/{path*}' }],
+          versionedRouters: {},
+        } as CreateTestRouterArgs,
+        expectedPath: '/test-path/{id}/{path}',
+        expectedState: 'Technical Preview',
+      },
+      {
+        name: 'router with beta stability',
+        routerConfig: {
+          routers: {
+            testRouter: {
+              routes: [
+                {
+                  path: '/test-path/{id}/{path*}',
+                  options: { availability: { stability: 'beta' }, access: 'public' },
+                },
+              ],
+            },
           },
-        },
-        versionedRouters: {
-          testVersionedRouter1: {
-            routes: [
-              {
-                path: '/v1-1',
-                options: {
-                  access: 'public',
-                  options: { availability: { stability: 'experimental' } },
-                  security: {
-                    authz: {
-                      requiredPrivileges: ['foo'],
+          versionedRouters: {},
+        } as CreateTestRouterArgs,
+        expectedPath: '/test-path/{id}/{path}',
+        expectedState: 'Beta',
+      },
+      {
+        name: 'router with stable stability',
+        routerConfig: {
+          routers: {
+            testRouter: {
+              routes: [
+                {
+                  path: '/test-path/{id}/{path*}',
+                  options: { availability: { stability: 'stable' }, access: 'public' },
+                },
+              ],
+            },
+          },
+          versionedRouters: {},
+        } as CreateTestRouterArgs,
+        expectedPath: '/test-path/{id}/{path}',
+        expectedState: 'Generally available',
+      },
+      {
+        name: 'router without availability',
+        routerConfig: {
+          routers: {
+            testRouter: {
+              routes: [{ path: '/test-path/{id}/{path*}' }],
+            },
+          },
+          versionedRouters: {},
+        } as CreateTestRouterArgs,
+        expectedPath: '/test-path/{id}/{path}',
+        expectedState: null, // No x-state expected
+      },
+      {
+        name: 'versioned router with experimental stability',
+        routerConfig: {
+          routers: {},
+          versionedRouters: {
+            testVersionedRouter: {
+              routes: [
+                {
+                  path: '/test-path',
+                  options: {
+                    access: 'public',
+                    options: { availability: { stability: 'experimental' } },
+                    security: {
+                      authz: {
+                        requiredPrivileges: ['foo'],
+                      },
                     },
                   },
                 },
-              },
-              {
-                path: '/v1-2',
-                options: {
-                  access: 'public',
-                  options: { availability: { stability: 'beta' } },
-                  security: {
-                    authz: {
-                      requiredPrivileges: ['foo'],
+              ],
+            },
+          },
+        } as CreateTestRouterArgs,
+        expectedPath: '/test-path',
+        expectedState: 'Technical Preview',
+      },
+      {
+        name: 'versioned router with beta stability',
+        routerConfig: {
+          routers: {},
+          versionedRouters: {
+            testVersionedRouter: {
+              routes: [
+                {
+                  path: '/test-path',
+                  options: {
+                    access: 'public',
+                    options: { availability: { stability: 'beta' } },
+                    security: {
+                      authz: {
+                        requiredPrivileges: ['foo'],
+                      },
                     },
                   },
                 },
-              },
-              {
-                path: '/v1-3',
-                options: {
-                  access: 'public',
-                  options: { availability: { stability: 'stable' } },
-                  security: {
-                    authz: {
-                      requiredPrivileges: ['foo'],
+              ],
+            },
+          },
+        } as CreateTestRouterArgs,
+        expectedPath: '/test-path',
+        expectedState: 'Beta',
+      },
+      {
+        name: 'versioned router with stable stability',
+        routerConfig: {
+          routers: {},
+          versionedRouters: {
+            testVersionedRouter: {
+              routes: [
+                {
+                  path: '/test-path',
+                  options: {
+                    access: 'public',
+                    options: { availability: { stability: 'stable' } },
+                    security: {
+                      authz: {
+                        requiredPrivileges: ['foo'],
+                      },
                     },
                   },
                 },
-              },
-            ],
+              ],
+            },
           },
-          testVersionedRouter2: {
-            routes: [
-              {
-                path: '/v2-1',
-                options: {
-                  access: 'public',
-                  security: {
-                    authz: {
-                      requiredPrivileges: ['foo'],
+        } as CreateTestRouterArgs,
+        expectedPath: '/test-path',
+        expectedState: 'Generally available',
+      },
+      {
+        name: 'versioned router without availability',
+        routerConfig: {
+          routers: {},
+          versionedRouters: {
+            testVersionedRouter: {
+              routes: [
+                {
+                  path: '/test-path',
+                  options: {
+                    access: 'public',
+                    security: {
+                      authz: {
+                        requiredPrivileges: ['foo'],
+                      },
                     },
                   },
                 },
-              },
-            ],
+              ],
+            },
           },
-        },
-      });
-      const result = await generateOpenApiDocument(
-        {
-          routers,
-          versionedRouters,
-        },
-        {
-          title: 'test',
-          baseUrl: 'https://test.oas',
-          version: '99.99.99',
-        }
-      );
-
-      // router paths
-      expect(result.paths['/1-1/{id}/{path}']!.get).toMatchObject({
-        'x-state': 'Technical Preview',
-      });
-      expect(result.paths['/1-2/{id}/{path}']!.get).toMatchObject({
-        'x-state': 'Beta',
-      });
-
-      expect(result.paths['/1-3/{id}/{path}']!.get).not.toMatchObject({
-        'x-state': expect.any(String),
-      });
-      expect(result.paths['/2-1/{id}/{path}']!.get).not.toMatchObject({
-        'x-state': expect.any(String),
-      });
+        } as CreateTestRouterArgs,
+        expectedPath: '/test-path',
+        expectedState: null, // No x-state expected
+      },
+    ];
 
-      // versioned router paths
-      expect(result.paths['/v1-1']!.get).toMatchObject({
-        'x-state': 'Technical Preview',
-      });
-      expect(result.paths['/v1-2']!.get).toMatchObject({
-        'x-state': 'Beta',
-      });
+    it.each(testCases)(
+      '$name: $expectedState',
+      async ({ routerConfig, expectedPath, expectedState }) => {
+        const [routers, versionedRouters] = createTestRouters(routerConfig);
+        const result = await generateOpenApiDocument(
+          {
+            routers,
+            versionedRouters,
+          },
+          {
+            title: 'test',
+            baseUrl: 'https://test.oas',
+            version: '99.99.99',
+          }
+        );
 
-      expect(result.paths['/v1-3']!.get).not.toMatchObject({
-        'x-state': expect.any(String),
-      });
-      expect(result.paths['/v2-1']!.get).not.toMatchObject({
-        'x-state': expect.any(String),
-      });
-    });
+        if (expectedState) {
+          expect(result.paths[expectedPath]!.get).toMatchObject({
+            'x-state': expectedState,
+          });
+        } else {
+          expect(result.paths[expectedPath]!.get).not.toMatchObject({
+            'x-state': expect.any(String),
+          });
+        }
+      }
+    );
   });
 
   it('merges operation objects', async () => {