Contribute to Kibana API docs locally

Overview

The Kibana API documentation is created by merging multiple OpenAPI documents. This is a step-by-step local development workflow. While CI runs these steps automatically on PR branches in the kibana repo, working locally enables you to validate, preview and debug before submitting your changes.

The workflow you follow depends on which set of APIs you're updating:

Code-generated

The core Kibana APIs are automatically generated from TypeScript route definitions in the codebase. Edit the .ts files in your plugin, and CI will regenerate the OpenAPI files when you push your PR. You can also run the generation locally for validation.

Manual YAML

Some teams, including Security and Observability, work with hand-edited YAML files in their plugin and package directories. For the complete list of files, refer to the merge scripts.

For more details, refer to the Kibana OAS docs README.

Quickstart

Follow these steps to contribute to Kibana API docs locally:

Clone the repository
1. Fork the Kibana repository to your GitHub account.
2. Clone your fork locally:
  Shell
```
git clone https://github.com/YOUR_USERNAME/kibana.git
cd kibana
```
Prepare your environment

Run this command to set up your Node.js environment:
Shell
```
nvm use
```
If you don't have Node.js installed, refer to the Kibana development getting started guide.
Install dependencies
Shell
```
yarn kbn bootstrap
```
Note

If dependencies are broken or bootstrap fails, run yarn kbn clean first. For more troubleshooting guidance, refer to the Kibana development getting started guide.
Make your docs changes
Code-generated
Edit the TypeScript route definitions in your plugin code. Add JSDoc comments, request/response schemas, and examples as needed, per the checklist.

Set an explicit operationId on public routes. SDK and CLI generators use this ID as the method and command name. If you omit it, the generator derives a name from the method and path, such as post-foo. Prefer kebab-case verb-resource names such as create-foo. For details, refer to Set an operation ID.

Always include version and lifecycle information using the availability option in your route definitions. This powers the version badges and tech preview labels that help users understand when an API was introduced and its stability status.
TypeScript
```
router.versioned.post({
  path: '/api/foo',
  access: 'public',
  summary: 'Create a foo resource',
  operationId: 'create-foo',
  options: {
    tags: ['example', 'oas-tag:Example APIs'],
    availability: {
      stability: 'experimental',
      since: '9.2.0',
    },
  },
});
```
The availability option includes two fields:
- stability: Sets the lifecycle state. The value maps to the label shown in the API docs.
  - 'experimental' renders as Experimental. The API can change or be removed in future versions.
  - 'tech_preview' renders as Technical preview.
  - 'stable' (default) renders as Generally available. The API is stable for production use.
- since: The version when the API was first added, for example '9.2.0'. The version appears in the Elastic Stack docs and is omitted from the serverless docs.
You can apply the availability option at two levels:
- Route level: in the route's options, as shown above.
- Parameter or property level: in a schema field's meta, using the same stability and since fields.
To document a single parameter or property, add availability to its meta:
TypeScript
```
access_control: schema.maybe(
  schema.object(
    {
      // properties
    },
    {
      meta: {
        availability: { stability: 'tech_preview', since: '9.5.0' },
        description: 'Optional conversation access control. Defaults to private.',
      },
    }
  )
),
```
The generator emits an x-state value on the property, so you don't need to write the version or lifecycle status into the description text.

Note

CI will automatically regenerate the OpenAPI files when you push your .ts changes. The next two steps show how to capture the snapshot and add examples locally, which is useful for validating changes before pushing or debugging issues.
Manual YAML
Edit the YAML files in the appropriate plugin or package directory. Refer to the README alongside each file for specific guidance on adding summaries, descriptions, tags, metadata, links, and examples.

Always include version and lifecycle information using the x-state field. This powers the version badges and tech preview labels in the API docs.
YAML
```
x-state: Technical Preview; added in 9.2.0
```
For stable/GA APIs, you can omit the lifecycle status:
YAML
```
x-state: added in 9.0.0
```
In these README files, you'll also find instructions for generating intermediate bundle files that capture your changes, and that are later used to generate the full API documentation.

The YAML files with the content changes and the intermediate bundle files are the minimum set of files required for creating a pull request. Without the intermediate bundle files, the automation won't pick up the changes and won't generate the full API documentation.

Review the checklist for best practices.

Once you've made your changes, skip the next two steps and proceed to generate the documentation.

Add examples to your routes

Concrete request and response examples significantly improve API documentation usability.

Inline TypeScript examples

For code-generated APIs, you can add examples directly in your route definitions. Examples are type-checked at development time, so shape errors are caught during authoring.

.addVersion({
  version: '2023-10-31',
  options: {
    oasOperationObject: () => ({
      requestBody: {
        content: {
          'application/json': {
            examples: {
              fooExample1: {
                summary: 'An example foo request',
                value: {
                  name: 'Cool foo!',
                } as FooResource,
              },
            },
          },
        },
      },
    }),
  },
  // ...
})

YAML examples

For code-generated APIs, you can reference a YAML file in your route definition:

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,
      },
    },
  },
})

For manually-maintained OpenAPI documents, add examples directly in your YAML files in the appropriate plugin or package directory.

Example YAML structure:

requestBody:
  content:
    application/json:
      examples:
        fooExample:
          summary: Foo example
          description: An example request of creating foo
          value:
            name: 'Cool foo!'
            enabled: true
responses:
  200:
    content:
      application/json:
        examples:
          exampleResponse:
            summary: Successful response
            value:
              id: '12345'
              name: 'Cool foo!'
              enabled: true
x-codeSamples:
- lang: cURL
  # label: A label which will be used as a title. Defaults to the lang value.
  source: |
    curl \
     -X POST "https://${KIBANA_URL}/api/foo" \
     -H "Authorization: ApiKey ${API_KEY}" \
     -H "kbn-xsrf: true" \
     -H "Content-Type: application/json" \
     -d '{
     ...
     }'
- lang: Console
  source: |
    POST kbn:/api/agent_builder/tools
    {
     ...
    }

Use examples (plural), not example (deprecated)
Optionally add examples in multiple languages. At a minimum, add curl and Console.

Optional: Capture code-generated output
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.

This step captures the OpenAPI specification that Kibana generates at runtime from your route definitions. It spins up a local Elasticsearch and Kibana cluster with your code changes. This generates the following output files in the oas_docs directory:
- bundle.json
- bundle.serverless.json
Prerequisites:
- Docker must be running.
To capture all the documented API paths, copy the command from capture_oas_snapshot.sh. For example:
Shell
```
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, you can capture the specific paths you're working on, though this minimized output should not be included in your pull request. For example:
Shell
```
node scripts/capture_oas_snapshot --update --include-path /api/your/specific/path
```
Manual YAML
This step is not applicable for manually-maintained OpenAPI documents. Your YAML files are used directly. Skip to the next step.
Generate docs

Run these commands to merge the OpenAPI documentation files:
Shell
```
cd oas_docs
make api-docs
```
This generates the following files:
- oas_docs/output/kibana.yaml
- oas_docs/output/kibana.serverless.yaml
Tip

Use make help to see available commands.
Lint your docs

Run this command to lint your OpenAPI files:
Shell
```
node ../scripts/validate_oas_docs.js
```
You can limit the scope of APIs that the linter checks by using --path or --only options. For details and examples, add --help.

Tip

When you open a pull request to submit API documentation changes, this linter runs in a CI check. It uses the --assert-no-error-increase option which causes the check to fail if the number of errors increases compared to the baseline.
Preview the API docs

Install bump-cli:
Shell
```
npm install -g bump-cli
```
Run this command to generate short-lived previews:
Shell
```
make api-docs-preview
```
Open a pull request

Once you're satisfied with your docs changes, create a pull request:
Code-generated
You have two options:
- Push only your .ts changes and let CI regenerate the OpenAPI files automatically
- Push both your .ts changes and locally-generated OpenAPI files together
The CI will validate your OpenAPI specs using the linter. Once approved, merge your changes and backport to the appropriate branches if needed.
Manual YAML
Push your edited YAML files. The CI will validate your OpenAPI specs using the linter. Once approved, merge your changes and backport to the appropriate branches if needed.