Loading

Contribute to Kibana API docs locally

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:

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.

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, see the Kibana OAS docs README.

Follow these steps to contribute to Kibana API docs locally:

  1. Fork and clone the repository

    1. Fork the Kibana repository to your GitHub account.

    2. Clone your fork locally:

      git clone https://github.com/YOUR_USERNAME/kibana.git
cd kibana

    3. Add the upstream repository as a remote:

      git remote add upstream https://github.com/elastic/kibana.git

  2. Prepare your environment

    Run this command to set up your Node.js environment:

    nvm use

    If you don't have Node.js installed, refer to the Kibana development getting started guide.

  3. Install dependencies 

    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.

  4. Make your docs changes

    Edit the TypeScript route definitions in your plugin code. Add JSDoc comments, request/response schemas, and examples as needed, per the checklist.

    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.

    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.

    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 the checklist for best practices.

    Once you've made your changes, skip the next two steps and proceed to "Generate docs".

  5. Add examples to your routes

    Beyond schema definitions, providing concrete request and response examples significantly improves 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, 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 manual YAML, 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
    1. Use examples (plural), not example (deprecated)

  6. (optional) Capture code-generated output

    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. See capture_oas_snapshot.sh for the full list of paths captured in CI.

    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
    • If you're an Elastician, ensure you're logged into Docker with your Elastic account

    Capture all API paths (recommended):

    node scripts/capture_oas_snapshot --update

    For faster iteration, capture the specific paths you're working on:

    node scripts/capture_oas_snapshot --update --include-path /api/your/specific/path

    This step is not applicable for Manual YAML. Your YAML files are used directly. Skip to the next step.

  7. Generate docs

    Run these commands to merge the OpenAPI documentation files:

    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.

  8. Lint your docs

    Run this command to lint your OpenAPI files:

    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.

  9. Preview the API docs

    1. Ensure bump-cli is installed and up to date:

      npm install -g bump-cli

    2. Run this command to generate a short-lived URL preview hosted on Bump.sh:

      make api-docs-preview

  10. Open a pull request

    Once you're satisfied with your docs changes, create a pull request:

    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.

    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.