[OAS][DOCS] Add temporary overlays for Kibana API documents (#189322)

.github/CODEOWNERS

@@ -1740,8 +1740,9 @@ packages/react @elastic/appex-sharedux
 /plugins/data_views/docs/openapi              @elastic/platform-docs
 oas_docs/.spectral.yaml                       @elastic/platform-docs
 oas_docs/kibana.info.serverless.yaml          @elastic/platform-docs
-oas_docs/kibana.serverless.yaml               @elastic/platform-docs
+oas_docs/kibana.info.yaml                     @elastic/platform-docs
 oas_docs/makefile                             @elastic/platform-docs
+oas_docs/overlays                             @elastic/platform-docs
 
 # Plugin manifests
 /src/plugins/**/kibana.jsonc @elastic/kibana-core

oas_docs/makefile

@@ -16,11 +16,11 @@
 .PHONY: api-docs
 api-docs: ## Generate kibana.serverless.yaml and kibana.yaml
 	@npx @redocly/cli join "kibana.info.serverless.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis_serverless.yaml" "../packages/core/saved-objects/docs/openapi/bundled_serverless.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" -o "output/kibana.serverless.yaml" "bundle.serverless.json" --prefix-components-with-info-prop title
-	@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/alerting/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml"  "../x-pack/plugins/cases/docs/openapi/bundled.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" "bundle.json" -o "output/kibana.yaml" --prefix-components-with-info-prop title
+	@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/alerting/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml"  "../x-pack/plugins/cases/docs/openapi/bundled.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml"  "bundle.json" -o "output/kibana.yaml" --prefix-components-with-info-prop title
 
 .PHONY: api-docs-stateful
 api-docs-stateful: ## Generate only kibana.yaml
-	@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/alerting/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/cases/docs/openapi/bundled.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" "bundle.json" -o "output/kibana.yaml" --prefix-components-with-info-prop title
+	@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/alerting/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/cases/docs/openapi/bundled.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml" "bundle.json" -o "output/kibana.yaml" --prefix-components-with-info-prop title
 # Temporarily omit "../x-pack/plugins/fleet/common/openapi/bundled.yaml" due to internals tag and tag sorting
 
 .PHONY: api-docs-serverless
@@ -29,8 +29,7 @@ api-docs-serverless: ## Generate only kibana.serverless.yaml
 
 .PHONY: api-docs-lint
 api-docs-lint: ## Run spectral API docs linter 
-	@npx @stoplight/spectral-cli lint "output/kibana.serverless.yaml" --ruleset ".spectral.yaml"
-	@npx @stoplight/spectral-cli lint "output/kibana.yaml" --ruleset ".spectral.yaml"
+	@npx @stoplight/spectral-cli lint "output/*.yaml" --ruleset ".spectral.yaml"
 
 .PHONY: api-docs-lint-stateful
 api-docs-lint-stateful: ## Run spectral API docs linter on kibana.yaml

oas_docs/overlays/kibana.overlays.serverless.yaml

@@ -4,6 +4,7 @@ info:
   title: Overlays for the Kibana API document
   version: 0.0.1
 actions:
+  # Clean up server definitions
   - target: '$.servers.*'
     description: Remove all servers so we can add our own.
     remove: true
@@ -14,6 +15,11 @@ actions:
         variables:
           kibana_url:
             default: localhost:5601
+  # Remove operation-level security definitions
+  - target: "$.paths['/api/status']['get'].security"
+    description: Remove system security definitions
+    remove: true
+  # Add a document-level security definition
   - target: '$.components.securitySchemes'
     description: Add an API key security scheme
     update:
@@ -27,4 +33,8 @@ actions:
     update:
       security:
         - apiKeyAuth: []
-
+  # Mark all operations as beta
+  - target: '$.paths[*][*]'
+    description: Add x-beta
+    update:
+      x-beta: true

oas_docs/overlays/kibana.overlays.yaml

@@ -4,6 +4,7 @@ info:
   title: Overlays for the Kibana API document
   version: 0.0.1
 actions:
+  # Clean up server definitions
   - target: '$.servers.*'
     description: Remove all servers so we can add our own.
     remove: true
@@ -14,6 +15,11 @@ actions:
         variables:
           kibana_url:
             default: localhost:5601
+  # Remove operation-level security definitions
+  - target: "$.paths['/api/status']['get'].security"
+    description: Remove system security definitions
+    remove: true
+  # Add document-level security definitions
   - target: '$.components.securitySchemes'
     description: Add an API key security scheme
     update:
@@ -34,6 +40,7 @@ actions:
       security:
         - apiKeyAuth: []
         - basicAuth: []
+  # Add an introduction to spaces
   - target: '$'
     description: Add an extra page about spaces
     update: