[Security Solution] Support external circular OpenAPI references by code generation

[maximpn]

Epic: https://github.com/elastic/security-team/issues/9723 (internal)

Summary

Support for local circular OpenAPi references was implemented in https://github.com/elastic/kibana/issues/186066. In general case we need to support multi files circular references in OpenAPI schemas.

kbn-openapi-generator package generates Zod schemas and related TS types from OpenAPI specification. It fails to handle recursive schemas. Code generation finished successfully but TS can't infer a proper type. See a related Zod documentation section.

We need to add support for recursive OpenAPI schemas.

Details

OpenAPI specification allows to use references to decompose and simplify schema declarations. References can also be used to declare a recursive schema with arbitrary recursive chain length across multiple files.

An example of external recursive schemas looks like

spec1.schema.yaml:

openapi: 3.0.0
info:
  title: Recursive schemas example
  version: 'not applicable'
paths: {}
components:
  x-codegen-enabled: true
  schemas:
    SchemaA:
      type: object
      properties:
        recursiveFieldB:
          $ref: './spec2.schema.yaml#/components/schemas/SchemaB'

spec2.schema.yaml:

openapi: 3.0.0
info:
  title: Recursive schemas example
  version: 'not applicable'
paths: {}
components:
  x-codegen-enabled: true
  schemas:
    SchemaB:
      type: object
      properties:
        recursiveFieldA:
          $ref: './spec1.schema.yaml#/components/schemas/SchemaA'

[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)