Skip to content

Commit fde835e

Browse files
authored
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.
1 parent 3af6444 commit fde835e

File tree

1 file changed

+18
-4
lines changed

1 file changed

+18
-4
lines changed

contribute-docs/api-docs/kibana-api-docs-quickstart.md

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ responses:
202202
:sync: code-generated
203203
204204
:::{note}
205-
**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.
205+
**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.
206206
:::
207207
208208
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
214214
- [Docker](https://docs.docker.com/get-docker/) must be running
215215
- If you're an Elastician, ensure you're logged into Docker with your Elastic account
216216
217-
**Capture all API paths** (recommended):
217+
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:
218218
219219
```bash
220-
node scripts/capture_oas_snapshot --update
220+
node scripts/capture_oas_snapshot \
221+
--include-path /api/status \
222+
--include-path /api/alerting/rule/ \
223+
--include-path /api/alerting/rules \
224+
--include-path /api/actions \
225+
--include-path /api/security/role \
226+
--include-path /api/spaces \
227+
--include-path /api/streams \
228+
--include-path /api/fleet \
229+
--include-path /api/saved_objects/_import \
230+
--include-path /api/saved_objects/_export \
231+
--include-path /api/maintenance_window \
232+
--include-path /api/agent_builder
233+
--update
221234
```
222235
223-
**For faster iteration**, capture the specific paths you're working on:
236+
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.
237+
For example:
224238

225239
```bash
226240
node scripts/capture_oas_snapshot --update --include-path /api/your/specific/path

0 commit comments

Comments
 (0)