Skip to content

Commit 3924bba

Browse files
committed
Add kibana local API docs workflow quickstart
1 parent fc348a6 commit 3924bba

File tree

1 file changed

+73
-3
lines changed

1 file changed

+73
-3
lines changed

extend/contribute/api-docs/quickstart.md

Lines changed: 73 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
---
2-
navigation_title: Contribute locally (Elasticsearch)
2+
navigation_title: Contribute locally: quickstarts
33
---
44

5-
# Contribute locally: Elasticsearch quickstart
5+
# Contribute to Elastic API docs locally: Quickstart guides
6+
7+
::::::::{tab-set}
8+
:::::::{tab-item} Elasticsearch
69

710
The Elasticsearch APIs are the foundation of the Elastic Stack and the largest API set we maintain. Because the workflow is quite complex, we created this quickstart guide to help you get started.
811

@@ -115,4 +118,71 @@ Once you're satisfied with your docs changes:
115118
3. Once approved, merge your changes and ensure they are backported to the appropriate branches
116119
::::
117120

118-
:::::
121+
:::::
122+
123+
:::::::
124+
125+
:::::::{tab-item} Kibana
126+
Follow these steps to capture live API specs from Kibana, generate OpenAPI documentation, and view a preview URL.
127+
128+
## Step 0: Set up Kibana environment
129+
130+
```bash
131+
cd kibana
132+
nvm use
133+
yarn kbn bootstrap
134+
```
135+
136+
**Note:** Run `yarn kbn clean` first if dependencies are broken.
137+
138+
## Step 0.1: Start Docker
139+
Ensure Docker is running, otherwise things will fail slowly.
140+
141+
## Step 1: Capture OAS snapshot
142+
143+
### 1.1: Ensure OAS is enabled
144+
`kibana/config/kibana.dev.yml` shoud look like this:
145+
```yaml
146+
server.oas.enabled: true
147+
```
148+
149+
### 1.2: Run capture command
150+
151+
You can just include your API set of interest, here it's for all plugins per [`capture_oas_snapshot.sh`](https://github.com/elastic/kibana/blob/main/.buildkite/scripts/steps/checks/capture_oas_snapshot.sh).
152+
153+
154+
```bash
155+
node scripts/capture_oas_snapshot \
156+
--update \
157+
--include-path /api/status \
158+
--include-path /api/alerting/rule/ \
159+
--include-path /api/alerting/rules \
160+
--include-path /api/actions \
161+
--include-path /api/security/role \
162+
--include-path /api/spaces \
163+
--include-path /api/streams \
164+
--include-path /api/fleet \
165+
--include-path /api/saved_objects/_import \
166+
--include-path /api/saved_objects/_export \
167+
--include-path /api/maintenance_window \
168+
--include-path /api/agent_builder
169+
```
170+
171+
**Output:** `oas_docs/bundle.json` and `oas_docs/bundle.serverless.json`
172+
173+
## Step 2: Generate docs
174+
```bash
175+
cd oas_docs
176+
make api-docs
177+
```
178+
179+
**Output:** `oas_docs/output/kibana.yaml` and `oas_docs/output/kibana.info.yaml`
180+
181+
## Step 3: Preview the API docs
182+
```bash
183+
make api-docs-preview
184+
```
185+
186+
This creates a short-lived URL preview on Bump.sh.
187+
:::::::
188+
::::::::

0 commit comments

Comments
 (0)