[Security Solution] Prevent adding enums with opaque default value

[maximpn]

Resolves: https://github.com/elastic/kibana/issues/188897 Reiteration of: https://github.com/elastic/kibana/pull/189986

Summary

This PR implements explicit restriction on enums with opaque default value since it could lead to subtle bugs. Default value should be specified either on consumer's side next to $ref or explicitly prefix or suffix enum's schema name with Default.

Details

Having a default value specified in a wrong place could lead to subtle bugs. For example we have a primitive schema reused in POST and PATCH operations. POST operation requires all fields in request body while PATCH allows to specify only some of them. Having a reused schema with a default value for the same field in POST and PATCH will lead to a bug. When this field is omitted for PATCH operation it will be defaulted to the default value and lead to opaque changes.

See Dmritrii's comment for additional information.

This PR adds functionality to OpenAPI Code Generator to check for enums with default values. Default value should be specified on consumer's side next to $ref or enum schema should be prefixed or suffixed with Default to pass the check otherwise Code Generator shows an error like below

Error: Unable to process /Users/maximp/work/repos/kibana-main/x-pack/plugins/security_solution/common/api/detection_engine/model/sorting.schema.yaml: Primitive schema SortOrder should not have default value specified since it's an anti-pattern leading to subtle bugs. Consider adding a default value into consumer node(s) next to $ref or renaming the schema to DefaultSortOrder.

Examples

A common spec file might look like

common.schema.yaml

openapi: 3.0.0
info:
  title: Common schemas
  version: 'not applicable'
paths: {}

components:
  schemas:
    EnumType:
      type: string
      enum:
        - value1
        - value2

    DefaultEnumType:
      type: string
      enum:
        - valueA
        - valueB
     default: valueA

And it's used in a route's spec where described enum schemas are consumed

spec.schema.yaml

openapi: 3.0.0
info:
  title: Update parameters
  version: '2023-10-31'
paths:
  /api/my/data:
    post:
      x-labels: [serverless, ess]
      x-codegen-enabled: true
      operationId: UpdateParameters
      summary: Updates parameters
      description: This a more detailed description why you should update the parameters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                someEnumField:
                  $ref: './common.schema.yaml#/components/schemas/EnumType'
                  default: value1
                anotherEnumField:
                  $ref: './common.schema.yaml#/components/schemas/DefaultEnumType'
      responses: ...

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

[kibana-ci]

:green_heart: Build Succeeded

• Buildkite Build
• Commit: 19844e4ee4a39de0bdf184a84ee3d7f5fd8b4e2b

Metrics [docs]

✅ unchanged

History

• :yellow_heart: Build #227242 was flaky 2d26d874bc2d90a003c2f693918e3a9863cbb1ed

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

cc @maximpn

[elasticmachine]

:robot: Jobs for this PR can be triggered through checkboxes. :construction:

:information_source: To trigger the CI, please tick the checkbox below :point_down:

• [ ] Click to trigger kibana-pull-request for this PR!
• [ ] Click to trigger kibana-deploy-project-from-pr for this PR!