From 176a2210d769ff004cb0669e002f69099febbec3 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 1 Aug 2024 09:38:01 -0700 Subject: [PATCH] [OAS][DOCS] Add temporary overlays for Kibana API documents (#189322) --- .github/CODEOWNERS | 3 ++- oas_docs/makefile | 7 +++---- oas_docs/overlays/kibana.overlays.serverless.yaml | 12 +++++++++++- oas_docs/overlays/kibana.overlays.yaml | 7 +++++++ 4 files changed, 23 insertions(+), 6 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 246497e110b94..d7055dbca4f44 100644 --- a/.github/CODEOWNERS +++ b/.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 diff --git a/oas_docs/makefile b/oas_docs/makefile index aa6bd1af38223..ec99abaf9e40d 100644 --- a/oas_docs/makefile +++ b/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 diff --git a/oas_docs/overlays/kibana.overlays.serverless.yaml b/oas_docs/overlays/kibana.overlays.serverless.yaml index 359d0d4bddac8..86a73d57c8561 100644 --- a/oas_docs/overlays/kibana.overlays.serverless.yaml +++ b/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 \ No newline at end of file diff --git a/oas_docs/overlays/kibana.overlays.yaml b/oas_docs/overlays/kibana.overlays.yaml index 7681a7201872a..d1acdf7712bf8 100644 --- a/oas_docs/overlays/kibana.overlays.yaml +++ b/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: