|
1 | 1 | --- |
2 | | -navigation_title: Contribute locally (Elasticsearch) |
| 2 | +navigation_title: Contribute locally: quickstarts |
3 | 3 | --- |
4 | 4 |
|
5 | | -# Contribute locally: Elasticsearch quickstart |
| 5 | +# Contribute to Elastic API docs locally: Quickstart guides |
| 6 | + |
| 7 | +::::::::{tab-set} |
| 8 | +:::::::{tab-item} Elasticsearch |
6 | 9 |
|
7 | 10 | 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. |
8 | 11 |
|
@@ -115,4 +118,71 @@ Once you're satisfied with your docs changes: |
115 | 118 | 3. Once approved, merge your changes and ensure they are backported to the appropriate branches |
116 | 119 | :::: |
117 | 120 |
|
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