[Security Solution] Implement shared components conflict resolution functionality

[maximpn]

Resolves: #188817

Summary

This PR adds automatic shared components conflict resolution functionality for OpenAPI merger. It boils down to a similar result as npx @redocly/cli join --prefix-components-with-info-prop title produces by prefixing shared components with document's title in each source.

OpenAPI bundler intentionally won't solve conflicts automatically since it's focused on bundling domain APIs where conflicts are usually indicators of upstream problems.

Details

While working with various OpenAPI specs it may happen that different specs use exactly the same name for some shared components but different definitions. It must be avoided inside one API domain but it's a usual situation when merging OpenAPI specs of different API domains. For example domains may define a shared Id or 404Response schemas where Id is a string in one domain and a number in another.

OpenAPI merger implemented in #188110 and OpenAPI bundler implemented in #171526 do not solve shared components related conflicts automatically. It works perfectly for a single API domain forcing engineers choosing shared schema names carefully.

This PR adds automatic shared components conflict resolution for OpenAPI merger. It prefixes shared component names with a normalized document's title.

OpenAPI bundler intentionally won't solve conflicts automatically since it's focused on bundling domain APIs where conflicts are usually indicators of upstream problems.

Example

Consider two following OpenAPI specs each defining local MySchema

spec1.schema.yaml

openapi: 3.0.3
info:
  title: My endpoint
  version: '2023-10-31'
paths:
  /api/some_api:
    get:
      operationId: MyEndpointGet
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MySchema'

components:
  schemas:
    MySchema:
      type: string
      enum:
        - value1

spec2.schema.yaml

openapi: 3.0.3
info:
  title: My another endpoint
  version: '2023-10-31'
paths:
  /api/another_api:
    get:
      operationId: MyAnotherEndpointGet
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MySchema'

components:
  schemas:
    MySchema:
      type: number

and a script to merge them

require('../../src/setup_node_env');
const { resolve } = require('path');
const { merge } = require('@kbn/openapi-bundler');
const { REPO_ROOT } = require('@kbn/repo-info');

(async () => {
  await merge({
    sourceGlobs: [
      `${REPO_ROOT}/oas_docs/spec1.schema.yaml`,
      `${REPO_ROOT}/oas_docs/spec2.schema.yaml`,
    ],
    outputFilePath: resolve(`${REPO_ROOT}/oas_docs/merged.yaml`),
    options: {
      mergedSpecInfo: {
        title: 'Merge result',
        version: 'my version',
      },
    },
  });
})();

will be merged successfully to

merged.yaml

openapi: 3.0.3
info:
  title: Merge result
  version: 'my version' 
paths:
  /api/another_api:
    get:
      operationId: MyAnotherEndpointGet
      responses:
        '200':
          content:
            application/json; Elastic-Api-Version=2023-10-31:
              schema:
                $ref: '#/components/schemas/My_another_endpoint_MySchema'
  /api/some_api:
    get:
      operationId: MyEndpointGet
      responses:
        '200':
          content:
            application/json; Elastic-Api-Version=2023-10-31:
              schema:
                $ref: '#/components/schemas/My_endpoint_MySchema'
components:
  schemas:
    My_another_endpoint_MySchema:
      type: number
    My_endpoint_MySchema:
      enum:
        - value1
      type: string

[elasticmachine]

Pinging @elastic/security-detections-response (Team:Detections and Resp)

[elasticmachine]

Pinging @elastic/security-solution (Team: SecuritySolution)

[elasticmachine]

Pinging @elastic/security-detection-rule-management (Team:Detection Rule Management)

[e40pud]

DE changes LGTM! Not sure if we need, but maybe we could add tests around new shared components conflict resolution functionality.

[maximpn]

Not sure if we need, but maybe we could add tests around new shared components conflict resolution functionality.

@e40pud it's a good idea, I added tests.

[maximpn]

@xcrzx thank you for careful review and good suggestions 🙏 I addressed your comments.

[xcrzx]

Thank you for quickly resolving all the comments. LGTM 👍

[patrykkopycinski]

Thank you @maximpn

[kibana-ci]

💛 Build succeeded, but was flaky

• Buildkite Build
• Commit: ea72c7b

Failed CI Steps

• Jest Integration Tests #3

Test Failures

• [job] [logs] Jest Integration Tests #3 / telemetry tasks endpoint-diagnostics should execute when scheduled

Metrics [docs]

Unknown metric groups

ESLint disabled in files

id	before	after	diff
@kbn/openapi-bundler	0	1	+1

ESLint disabled line counts

id	before	after	diff
@kbn/openapi-bundler	0	2	+2

Total ESLint disabled count

id	before	after	diff
@kbn/openapi-bundler	0	3	+3

History

• 💔 Build #223785 failed 5e2414f4e4a5edef8b0a988e2bbc69d21bf8b1a1
• 💔 Build #223757 failed 5e2414f4e4a5edef8b0a988e2bbc69d21bf8b1a1
• 💔 Build #223495 failed ee41473d3f3ed34abc043c4a1018feb44f24e1ee
• 💛 Build #222989 was flaky 8bf2baa29e19202c5fd547fdb8f2cb55b309c40f
• 💛 Build #222933 was flaky 8a9de0008a960f95380ca3fb8ab90fd261a3cda8

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @maximpn