API Explorer

The API Explorer renders OpenAPI specifications as interactive API documentation. When you configure it in your content set, docs-builder automatically generates pages for each API operation, request and response schemas, shared type definitions, and inline examples.

Add the api key to your docset.yml file to enable the API Explorer. The key maps product names to OpenAPI JSON specification files. Paths are relative to the folder that contains docset.yml.

api:
  elasticsearch: elasticsearch-openapi.json
  kibana: kibana-openapi.json
		

Each product key produces its own section of API documentation. For example, elasticsearch generates pages under /api/elasticsearch/ and kibana generates pages under /api/kibana/.

The api key is only valid in docset.yml. You can't use it in toc.yml files.

OpenAPI specification files must be in JSON format and located in the same folder as your docset.yml (or in a subfolder of it). The path you specify in api is resolved relative to the docset.yml location.

For example, if your content set is structured like this:

docs/
  docset.yml
  elasticsearch-openapi.json
  kibana-openapi.json
  index.md
  ...
		

Your docset.yml references the specs as follows:

api:
  elasticsearch: elasticsearch-openapi.json
  kibana: kibana-openapi.json
		

The API Explorer generates documentation in two scenarios:

• docs-builder build: API docs are generated as part of the standard build. Use --skip-api to skip generation for faster iteration on content.
• docs-builder serve: API docs are generated on startup and regenerated automatically when spec files change.

You can reference API pages in your toc.yml or docset.yml navigation using cross-link syntax:

toc:
  - file: index.md
  - title: Elasticsearch API Reference
    crosslink: elasticsearch://api/elasticsearch/
		

The API Explorer generates the following types of pages from your OpenAPI spec:

• Landing page: An overview of the API grouped by tag
• Operation pages: One page per API operation, with the HTTP method, path, parameters, request body, response schemas, and examples
• Schema type pages: Dedicated pages for complex shared types such as QueryContainer and AggregationContainer