Add stepper, info

Author: leemthompo

extend/contribute/api-docs/quickstart.md

@@ -1,9 +1,11 @@
 ---
-navigation_title: Contribute locally: quickstarts
+navigation_title: Quickstarts
 ---
 
 # Contribute to Elastic API docs locally: Quickstart guides
 
+This guide provides step-by-step workflows for contributing to Elasticsearch and {{kib}} API documentation locally. These workflows enable you to validate, preview, and debug your changes before submitting them for review.
+
 ::::::::{tab-set}
 :::::::{tab-item} Elasticsearch
 
@@ -99,6 +101,7 @@ You should try to fix all linter warnings and not just errors. Fixing errors alo
 ```shell
 make overlay-docs
 ```
+::::
 
 ::::{step} Preview your changes
 Generate a preview of how your docs will appear:
@@ -122,34 +125,134 @@ Once you're satisfied with your docs changes:
 
 :::::::
 
-:::::::{tab-item} Kibana
-Follow these steps to capture live API specs from Kibana, generate OpenAPI documentation, and view a preview URL.
+:::::::{tab-item} {{kib}}
+
+Follow these steps to capture live API specs from {{kib}}, generate OpenAPI documentation, and view a preview URL.
 
-## Step 0: Set up Kibana environment
+:::{tip}
+Refer to the {{kib}} [OAS docs README](https://github.com/elastic/kibana/tree/main/oas_docs#kibana-api-reference-documentation) for more information.
+:::
+
+:::::{stepper}
+
+::::{step} Set up {{kib}} environment
 
 ```bash
 cd kibana
 nvm use
 yarn kbn bootstrap
 ```
 
-**Note:** Run `yarn kbn clean` first if dependencies are broken.
+:::{note}
+Run `yarn kbn clean` first if dependencies are broken.
+:::
+::::
 
-## Step 0.1: Start Docker
+::::{step} Start Docker
 Ensure Docker is running, otherwise things will fail slowly.
+::::
 
-## Step 1: Capture OAS snapshot
+::::{step} Enable OAS in {{kib}}
 
-### 1.1: Ensure OAS is enabled
-`kibana/config/kibana.dev.yml` shoud look like this:
+Ensure `kibana/config/kibana.dev.yml` contains:
 ```yaml
 server.oas.enabled: true
 ```
+::::
 
-### 1.2: Run capture command
+::::{step} Add examples to your routes (optional)
+
+Beyond schema definitions, providing concrete request and response examples significantly improves API documentation usability. Examples are type-checked at development time, so shape errors are caught during authoring.
+
+:::{dropdown} Inline TypeScript examples
+You can add examples directly in your route definitions:
+```typescript
+.addVersion({
+  version: '2023-10-31',
+  options: {
+    oasOperationObject: () => ({
+      requestBody: {
+        content: {
+          'application/json': {
+            examples: {
+              fooExample1: {
+                summary: 'An example foo request',
+                value: {
+                  name: 'Cool foo!',
+                } as FooResource,
+              },
+            },
+          },
+        },
+      },
+    }),
+  },
+  // ...
+})
+```
+:::
 
-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).
+:::{dropdown} YAML-based examples
+For pre-existing YAML examples:
+```typescript
+import path from 'node:path';
+
+const oasOperationObject = () => path.join(__dirname, 'foo.examples.yaml');
+
+.addVersion({
+  version: '2023-10-31',
+  options: {
+    oasOperationObject,
+  },
+  validate: {
+    request: {
+      body: fooResource,
+    },
+    response: {
+      200: {
+        body: fooResourceResponse,
+      },
+    },
+  },
+})
+```
 
+Where `foo.examples.yaml` contains:
+```yaml
+requestBody:
+  content:
+    application/json:
+      examples: # Use examples (plural), not example (deprecated)
+        fooExample:
+          summary: Foo example
+          description: >
+            An example request of creating foo.
+          value:
+            name: 'Cool foo!'
+        fooExampleRef:
+          # You can use JSONSchema $refs to organize further
+          $ref: "./examples/foo_example_i_factored_out_of_this_file.yaml"
+responses:
+  200:
+    content:
+      application/json:
+        examples:
+          # Apply a similar pattern for response examples
+```
+:::
+::::
+
+::::{step} Capture OAS snapshot
+
+:::{tip}
+Skip this step if you've only edited manually-maintained YAML files (like `bundled.yaml`, `*.schema.yaml`, or `kibana.info.serverless.yaml`).
+:::
+
+Run this step when you've made changes to route definitions, request/response schemas, or added new HTTP APIs in your plugin code.
+
+This spins up a local {{es}} and {{kib}} cluster with your code changes, then extracts the OpenAPI specification that {{kib}} generates at runtime based on your route definitions and schemas.
+
+This example includes all plugins per [`capture_oas_snapshot.sh`](https://github.com/elastic/kibana/blob/main/.buildkite/scripts/steps/checks/capture_oas_snapshot.sh):
 
 ```bash
 node scripts/capture_oas_snapshot \
@@ -168,21 +271,28 @@ node scripts/capture_oas_snapshot \
   --include-path /api/agent_builder
 ```
 
-**Output:** `oas_docs/bundle.json` and `oas_docs/bundle.serverless.json`
+This generates `oas_docs/bundle.json` and `oas_docs/bundle.serverless.json`.
+::::
 
-## Step 2: Generate docs
+::::{step} Generate docs
 ```bash
 cd oas_docs
 make api-docs
 ```
 
-**Output:** `oas_docs/output/kibana.yaml` and `oas_docs/output/kibana.info.yaml`
+This generates `oas_docs/output/kibana.yaml` and `oas_docs/output/kibana.info.yaml`.
+
+Use `make help` to see available commands.
+::::
 
-## Step 3: Preview the API docs
+::::{step} Preview the API docs
 ```bash
 make api-docs-preview
 ```
 
 This creates a short-lived URL preview on Bump.sh.
-:::::::
-::::::::
+::::
+
+:::::
+
+:::::::