From fde835eca857e77f77b41176611d1c3513df18b8 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 19 Nov 2025 11:38:44 -0800 Subject: [PATCH 1/2] Update kibana-api-docs-quickstart.md This PR updates the guidance around the use of the capture_oas_snapshot command, since omitting `include-path` yields different results than what we're publishing. --- .../api-docs/kibana-api-docs-quickstart.md | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/contribute-docs/api-docs/kibana-api-docs-quickstart.md b/contribute-docs/api-docs/kibana-api-docs-quickstart.md index 178ee3e50b..e28557dd03 100644 --- a/contribute-docs/api-docs/kibana-api-docs-quickstart.md +++ b/contribute-docs/api-docs/kibana-api-docs-quickstart.md @@ -202,7 +202,7 @@ responses: :sync: code-generated :::{note} -**This step is optional.** CI will automatically capture the snapshot when you push your `.ts` changes. Running this locally is useful for validating changes before pushing or debugging issues. See [`capture_oas_snapshot.sh`](https://github.com/elastic/kibana/blob/main/.buildkite/scripts/steps/checks/capture_oas_snapshot.sh) for the full list of paths captured in CI. +**This step is optional.** CI will automatically capture the snapshot when you push your `.ts` changes. Running this locally is useful for validating changes before pushing or debugging issues. ::: This step captures the OpenAPI specification that {{kib}} generates at runtime from your route definitions. It spins up a local {{es}} and {{kib}} cluster with your code changes. This generates the following output files in the `oas_docs` directory: @@ -214,13 +214,27 @@ This step captures the OpenAPI specification that {{kib}} generates at runtime f - [Docker](https://docs.docker.com/get-docker/) must be running - If you're an Elastician, ensure you're logged into Docker with your Elastic account -**Capture all API paths** (recommended): +To capture all the documented API paths, copy the command from [`capture_oas_snapshot.sh`](https://github.com/elastic/kibana/blob/main/.buildkite/scripts/steps/checks/capture_oas_snapshot.sh). For example: ```bash -node scripts/capture_oas_snapshot --update +node scripts/capture_oas_snapshot \ + --include-path /api/status \ + --include-path /api/alerting/rule/ \ + --include-path /api/alerting/rules \ + --include-path /api/actions \ + --include-path /api/security/role \ + --include-path /api/spaces \ + --include-path /api/streams \ + --include-path /api/fleet \ + --include-path /api/saved_objects/_import \ + --include-path /api/saved_objects/_export \ + --include-path /api/maintenance_window \ + --include-path /api/agent_builder + --update ``` -**For faster iteration**, capture the specific paths you're working on: +For faster iteration**, you can capture the specific paths you're working on, though this minimized output should not be included in your pull request. +For example: ```bash node scripts/capture_oas_snapshot --update --include-path /api/your/specific/path From d8d99a301220529d618c12f02a041b0c476dfb02 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 19 Nov 2025 12:28:31 -0800 Subject: [PATCH 2/2] Update contribute-docs/api-docs/kibana-api-docs-quickstart.md --- contribute-docs/api-docs/kibana-api-docs-quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/api-docs/kibana-api-docs-quickstart.md b/contribute-docs/api-docs/kibana-api-docs-quickstart.md index e28557dd03..1971b37833 100644 --- a/contribute-docs/api-docs/kibana-api-docs-quickstart.md +++ b/contribute-docs/api-docs/kibana-api-docs-quickstart.md @@ -233,7 +233,7 @@ node scripts/capture_oas_snapshot \ --update ``` -For faster iteration**, you can capture the specific paths you're working on, though this minimized output should not be included in your pull request. +For faster iteration, you can capture the specific paths you're working on, though this minimized output should not be included in your pull request. For example: ```bash