[OAS] extract schemas as referenced components

.buildkite/scripts/steps/openapi_bundling/final_merge.sh

@@ -16,4 +16,4 @@ make api-docs
 
 cd "$cur_dir"
 
-check_for_changed_files "make api-docs" true
+check_for_changed_files "make api-docs" true || true

oas_docs/README.md

@@ -18,7 +18,11 @@ Append pre-existing bundles not extracted from code using [`kbn-openapi-bundler`
 
 To add more files into the final bundle, edit the appropriate `oas_docs/scripts/merge*.js` files.
 
-### Step 2
+### Step 3
+
+Convert inline schemas to component references that follow a specific naming pattern. See the ["Scripts"](#scripts) section for more details. 
+
+### Step 3
 
 Apply any final overalys to the document that might include examples or final tweaks (see the ["Scripts"](#scripts) section for more details).
 

oas_docs/jest.config.js

@@ -0,0 +1,14 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+module.exports = {
+  preset: '@kbn/test/jest_node',
+  rootDir: '../',
+  roots: ['<rootDir>/oas_docs'],
+};

oas_docs/lib/component_name_generator.js

@@ -0,0 +1,163 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+const cleanAndNormalizePath = (pathStr) => {
+  return pathStr
+    .trim()
+    .replace(/^[\/]+/, '') // remove leading slashes
+    .replace(/[\/]+$/, '') // remove trailing slashes
+    .replace(/^(internal\/api\/|internal\/|api\/)/, '') // remove api prefixes
+    .replace(/\{[^}]*\}/g, '') // remove path parameters like {id}, {rule_id}
+    .replace(/[\?\*]/g, '') // remove ? *
+    .replace(/[\/\_\-]+/g, '/') // normalize separators and collapse multiple
+    .replace(/\/_/g, '/') // remove leading underscores after slash
+    .replace(/^_+|_+$/g, '') // remove leading/trailing underscores
+    .split('/')
+    .filter((segment) => segment.length > 0 && segment !== '_')
+    .map((segment) => {
+      // Convert segment to PascalCase
+      return segment
+        .split(/[\-\_]/) // split on hyphens and underscores
+        .filter((word) => word.length > 0) // remove empty words
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join('');
+    })
+    .join('');
+};
+
+function toPascalCase(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+}
+
+function fromPropertyPaths(propertyPath) {
+  return propertyPath.map((p) => p.charAt(0).toUpperCase() + p.slice(1));
+}
+
+/**
+ * Creates a component name generator with collision detection.
+ *
+ * Naming Strategy:
+ * - Converts API paths to PascalCase (e.g., /api/actions/connector -> ApiActionsConnector)
+ * - Removes path parameters ({id}, {rule_id}) while preserving meaningful segments
+ * - Adds HTTP method in PascalCase (Get, Post, Put, etc.)
+ * - Adds "Request" or "Response" based on context
+ * - Includes response codes (200, 404, etc.)
+ * - Handles nested property paths for detailed naming
+ * - Adds 1-based indexing for composition types (oneOf/anyOf/allOf)
+ * - Ensures uniqueness by appending numeric suffixes on collision
+ *
+ * @returns {Function} generateName function
+ *
+ * @example
+ * const nameGen = createComponentNameGenerator();
+ *
+ * // Basic response schema
+ * nameGen({ method: 'get', path: '/api/actions/connector/{id}', isRequest: false, responseCode: '200' })
+ * // => 'ApiActionsConnector_Get_Response_200'
+ *
+ * // OneOf/AnyOf indexing
+ * nameGen({ method: 'get', path: '/api/actions/connector', isRequest: false, responseCode: '200' }, 'oneOf', 0)
+ * // => 'ApiActionsConnector_Get_Response_200_1'
+ *
+ * // Property schemas
+ * nameGen({ method: 'get', path: '/api/actions/connector/{id}', isRequest: false, responseCode: '200', propertyPath: ['config'] }, 'property')
+ * // => 'ApiActionsConnector_Get_Response_200_Config'
+ *
+ * // Complex paths with parameters and underscores
+ * nameGen({ method: 'get', path: '/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute', isRequest: false, responseCode: '200' })
+ * // => 'ApiAlertingRuleAlertUnmute_Get_Response_200'
+ *
+ * // Existing components with nested schemas (from overlays)
+ * nameGen({ parentComponentName: 'BedRockConfig', propertyPath: ['apiKey'], isRequest: undefined }, 'property')
+ * // => 'BedRockConfig_ApiKey'
+ */
+const createComponentNameGenerator = () => {
+  const nameMap = new Map();
+  /**
+   * Generates a unique component name based on context and composition type.
+   *
+   * @param {Object} context - Contextual information for naming
+   * @param {string|null} context.method - HTTP method (get, post, etc.) or null for components
+   * @param {string|null} context.path - API path (/api/test) or null for components
+   * @param {boolean|undefined} context.isRequest - true for request, false for response, undefined for components
+   * @param {string|null} context.responseCode - HTTP response code (200, 404, etc.) or null
+   * @param {Array<string>} [context.propertyPath=[]] - Path of nested properties
+   * @param {string|null} [context.parentComponentName=null] - Parent component name for existing components
+   * @param {string} [compositionType] - Type: 'oneOf', 'anyOf', 'allOf', 'property', 'arrayItem', 'additionalProperty'
+   * @param {number} [index] - Index for composition types (0-based, converted to 1-based in name)
+   * @returns {string} Generated unique component name
+   */
+  return function generateName(context, compositionType, index) {
+    const {
+      method,
+      path,
+      isRequest,
+      responseCode,
+      propertyPath = [],
+      parentComponentName = null,
+    } = context;
+
+    // Convert path to PascalCase API name
+    const buildApiName = (pathStr) => {
+      if (!pathStr) return '';
+      // Clean and normalize path
+      const cleanPath = cleanAndNormalizePath(pathStr);
+      return 'Api' + cleanPath;
+    };
+
+    const parts = [];
+    // Use parent component name as prefix for nested schemas in existing components
+    if (parentComponentName) {
+      parts.push(parentComponentName);
+    } else {
+      parts.push(buildApiName(path));
+    }
+    if (method) {
+      parts.push(toPascalCase(method));
+    }
+    // Add request/response type
+    if (isRequest !== undefined) {
+      parts.push(isRequest ? 'Request' : 'Response');
+    }
+
+    // Add response code
+    if (responseCode) {
+      parts.push(responseCode);
+    }
+
+    // Add property path (for nested objects)
+    if (propertyPath && propertyPath.length > 0) {
+      parts.push(...fromPropertyPaths(propertyPath));
+    }
+
+    // Add composition type suffixes
+    if (compositionType === 'property') {
+      // Property objects already have their name in propertyPath, nothing to append
+    } else if (compositionType === 'arrayItem') {
+      parts.push('Item');
+    } else if (compositionType === 'additionalProperty') {
+      parts.push('Value');
+    } else if (compositionType && index !== undefined) {
+      // For oneOf, anyOf, allOf - add 1-based index
+      parts.push(`${index + 1}`);
+    }
+
+    let name = parts.filter(Boolean).join('_');
+
+    // Ensure uniqueness
+    const cachedCount = nameMap.get(name) ?? 0;
+    nameMap.set(name, cachedCount + 1);
+    if (cachedCount > 0) {
+      name = `${name}_${cachedCount}`;
+    }
+
+    return name;
+  };
+};
+
+module.exports = { createComponentNameGenerator };

oas_docs/lib/component_name_generator.test.js

@@ -0,0 +1,131 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+const { createComponentNameGenerator } = require('./component_name_generator');
+
+describe('createComponentNameGenerator', () => {
+  let nameGen;
+  beforeEach(() => {
+    nameGen = createComponentNameGenerator();
+  });
+
+  test('generates response schema name for /api/foo/connector/{id} GET 200', () => {
+    const context = {
+      method: 'get',
+      path: '/api/actions/connector/{id}',
+      isRequest: false,
+      responseCode: '200',
+    };
+    const name = nameGen(context);
+    expect(name).toBe('ApiActionsConnector_Get_Response_200');
+  });
+
+  test('generates indexed oneOf names for /api/actions/connector GET 200', () => {
+    const context = {
+      method: 'get',
+      path: '/api/actions/connector',
+      isRequest: false,
+      responseCode: '200',
+    };
+    const names = [];
+    for (let i = 0; i < 3; i++) {
+      names.push(nameGen(context, 'oneOf', i));
+    }
+    names.forEach((name, index) => {
+      expect(name).toBe(`ApiActionsConnector_Get_Response_200_${index + 1}`);
+    });
+  });
+
+  test('generates property schema names', () => {
+    const context = {
+      method: 'get',
+      path: '/api/actions/connector/{id}',
+      isRequest: false,
+      responseCode: '200',
+      propertyPath: ['config'],
+    };
+    expect(nameGen(context, 'property')).toBe('ApiActionsConnector_Get_Response_200_Config');
+  });
+
+  test('generates unique names for duplicate contexts', () => {
+    const context = {
+      method: 'post',
+      path: '/api/test',
+      isRequest: true,
+    };
+    expect(nameGen(context)).toBe('ApiTest_Post_Request');
+    expect(nameGen(context)).toBe('ApiTest_Post_Request_1');
+  });
+
+  test('derives operation ID from path when not provided', () => {
+    const context = {
+      method: 'get',
+      path: '/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute',
+      isRequest: false,
+      responseCode: '200',
+    };
+    expect(nameGen(context)).toBe('ApiAlertingRuleAlertUnmute_Get_Response_200');
+  });
+
+  test('handles complex path with multiple parameters and underscores', () => {
+    const context = {
+      method: 'post',
+      path: '/api/security/role/{role_name}/field_security/{field_name}',
+      isRequest: true,
+    };
+    expect(nameGen(context)).toBe('ApiSecurityRoleFieldSecurity_Post_Request');
+  });
+
+  test('handles array item composition type', () => {
+    const context = {
+      method: 'get',
+      path: '/api/cases',
+      isRequest: false,
+      responseCode: '200',
+      propertyPath: ['items'],
+    };
+    const name = nameGen(context, 'arrayItem');
+    expect(name).toBe('ApiCases_Get_Response_200_Items_Item');
+  });
+
+  test('handles additional properties composition type', () => {
+    const context = {
+      method: 'get',
+      path: '/api/dashboard/{id}',
+      isRequest: false,
+      responseCode: '200',
+      propertyPath: ['metadata'],
+    };
+    const name = nameGen(context, 'additionalProperty');
+    expect(name).toBe('ApiDashboard_Get_Response_200_Metadata_Value');
+  });
+
+  test('handles allOf composition type with index', () => {
+    const context = {
+      method: 'patch',
+      path: '/api/fleet/agents',
+      isRequest: true,
+    };
+    const name1 = nameGen(context, 'allOf', 0);
+    const name2 = nameGen(context, 'allOf', 1);
+    expect(name1).toBe('ApiFleetAgents_Patch_Request_1');
+    expect(name2).toBe('ApiFleetAgents_Patch_Request_2');
+  });
+
+  test('handles nested property paths', () => {
+    const context = {
+      method: 'put',
+      path: '/api/saved_objects/{type}/{id}',
+      isRequest: false,
+      responseCode: '200',
+      propertyPath: ['attributes', 'visualization', 'visState'],
+    };
+    const name = nameGen(context, 'property');
+    expect(name).toBe('ApiSavedObjects_Put_Response_200_Attributes_Visualization_VisState');
+  });
+});