[DOCS] OpenAPI discriminator error

[lcawl]

Tell us about the issue

Description:

The OpenAPI document contains some linting errors that are non-trivial to fix:

[8] logstash-api.yaml:1088:17 at #/paths/~1_node~1stats~1pipelines~1{pipeline_name}/get/responses/200/content/application~1json/schema

Example validation errored: discriminator: "type" must be required.

1086 |             application/json:
1087 |               schema:
1088 |                 allOf:
1089 | #                  - $ref: "#/components/schemas/Common"
   … | < 2 more lines >
1092 |               examples:
1093 |                 PipelineWithPersistedQueue:
1094 |                   description: A pipeline with a persisted queue.

referenced from logstash-api.yaml:1087:15 at #/paths/~1_node~1stats~1pipelines~1{pipeline_name}/get/responses/200/content/application~1json 

Warning was generated by the no-invalid-media-type-examples rule.

It relates to the following part of the specification:

    PipelineQueueStats:
      type: object
      properties:
        queue:
          type: object
          oneOf:
            - type: object
               ...
            - type: object
               ...
          discriminator:
            propertyName: type

I believe that discriminators are optional but when they're present it means the specified property (in this case type) must be a required property not an optional one. I did a quick test of:

• (A) removing the discriminator clause and alternatively
• (B) adding the required: - type in each of the objects in that oneOf section of PipelineQueueStats.

Both resolved the original linting message but I'm not sure which is the accurate indication of the API behaviour (i.e. is the "type" property truly a required property? It seemed like it was absent from some of the examples which makes me think it's actually an optional property and therefore can't be used as a discriminator). Both of my attempted fixes prompted a bunch more linting messages related to how/if the examples matched the specification so I think it requires more expertise and knowledge of this API than I possess. It may also be a situation where the generic linting tools can't handle the complexity of our APIs, so if this seems to be the case we can turn off some of those linting rules to avoid future misdirection.

URL:

https://github.com/elastic/logstash/blob/main/docs/static/spec/openapi/logstash-api.yaml

Anything else?