[Security Solution] Sort root level tags alphabetically by name in th…

…e result bundle (#189482)

**Resolves:** #189463

## Summary

This PR adds functionality to produce result bundle with by default sorted root level OpenAPI `tags` alphabetically by name as requested by the Docs Engineering team.

## Details

Bump.sh (new API reference documentation platform) uses OpenAPI tags for grouping API endpoints together. It displays tags encountered order which isn't always a desired one. To streamline displaying tags we need them sorted alphabetically by name.

## Screenshots

**Example API reference documentation page BEFORE**
![image](https://github.com/user-attachments/assets/f66f0488-2a94-4e40-be91-808782b489b2)

**Example API reference documentation page AFTER**
![image](https://github.com/user-attachments/assets/24ef9844-3d9d-4309-a1f0-69a2a9a23f08)

packages/kbn-openapi-bundler/src/bundler/merge_documents/merge_tags.ts

@@ -19,5 +19,13 @@ export function mergeTags(
 
   const merged = mergeArrays(tagsArrayOfArrays);
 
-  return merged.length > 0 ? merged : undefined;
+  if (merged.length === 0) {
+    return;
+  }
+
+  // To streamline API endpoints categorization it's expected that
+  // tags are sorted alphabetically by name
+  merged.sort((a, b) => a.name.localeCompare(b.name));
+
+  return merged;
 }

packages/kbn-openapi-bundler/tests/bundler/result_overrides/sort_tags.test.ts

@@ -0,0 +1,63 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { bundleSpecs } from '../bundle_specs';
+import { createOASDocument } from '../../create_oas_document';
+
+describe('OpenAPI Bundler - sort tags', () => {
+  it('sorts tags in the result bundle', async () => {
+    const spec1 = createOASDocument({
+      paths: {
+        '/api/some_api': {
+          get: {
+            responses: {},
+          },
+        },
+      },
+      tags: [
+        { name: 'Some tag name', description: 'Some description' },
+        { name: '1 tag', description: 'Some description' },
+      ],
+    });
+    const spec2 = createOASDocument({
+      paths: {
+        '/api/some_api': {
+          post: {
+            responses: {},
+          },
+        },
+      },
+      tags: [{ name: 'Another tag name', description: 'Another description' }],
+    });
+    const spec3 = createOASDocument({
+      paths: {
+        '/api/some_api': {
+          put: {
+            responses: {},
+          },
+        },
+      },
+      tags: [{ name: 'Spec3 tag name', description: 'Spec3 tag description' }],
+    });
+
+    const [bundledSpec] = Object.values(
+      await bundleSpecs({
+        1: spec1,
+        2: spec2,
+        3: spec3,
+      })
+    );
+
+    expect(bundledSpec.tags).toEqual([
+      { name: '1 tag', description: 'Some description' },
+      { name: 'Another tag name', description: 'Another description' },
+      { name: 'Some tag name', description: 'Some description' },
+      { name: 'Spec3 tag name', description: 'Spec3 tag description' },
+    ]);
+  });
+});

packages/kbn-openapi-bundler/tests/create_oas_document.ts

@@ -15,6 +15,7 @@ export function createOASDocument(overrides: {
   components?: OpenAPIV3.ComponentsObject;
   servers?: OpenAPIV3.ServerObject[];
   security?: OpenAPIV3.SecurityRequirementObject[];
+  tags?: OpenAPIV3.TagObject[];
 }): OpenAPIV3.Document {
   const document: OpenAPIV3.Document = {
     openapi: overrides.openapi ?? '3.0.3',
@@ -39,5 +40,9 @@ export function createOASDocument(overrides: {
     document.security = overrides.security;
   }
 
+  if (overrides.tags) {
+    document.tags = overrides.tags;
+  }
+
   return document;
 }

packages/kbn-openapi-bundler/tests/merger/result_overrides/sort_tags.test.ts

@@ -0,0 +1,63 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { mergeSpecs } from '../merge_specs';
+import { createOASDocument } from '../../create_oas_document';
+
+describe('OpenAPI Merger - sort tags', () => {
+  it('sorts tags in the result bundle', async () => {
+    const spec1 = createOASDocument({
+      paths: {
+        '/api/some_api': {
+          get: {
+            responses: {},
+          },
+        },
+      },
+      tags: [
+        { name: 'Some tag name', description: 'Some description' },
+        { name: '1 tag', description: 'Some description' },
+      ],
+    });
+    const spec2 = createOASDocument({
+      paths: {
+        '/api/some_api': {
+          post: {
+            responses: {},
+          },
+        },
+      },
+      tags: [{ name: 'Another tag name', description: 'Another description' }],
+    });
+    const spec3 = createOASDocument({
+      paths: {
+        '/api/some_api': {
+          put: {
+            responses: {},
+          },
+        },
+      },
+      tags: [{ name: 'Spec3 tag name', description: 'Spec3 tag description' }],
+    });
+
+    const [mergedSpec] = Object.values(
+      await mergeSpecs({
+        1: spec1,
+        2: spec2,
+        3: spec3,
+      })
+    );
+
+    expect(mergedSpec.tags).toEqual([
+      { name: '1 tag', description: 'Some description' },
+      { name: 'Another tag name', description: 'Another description' },
+      { name: 'Some tag name', description: 'Some description' },
+      { name: 'Spec3 tag name', description: 'Spec3 tag description' },
+    ]);
+  });
+});