--- title: Add core content description: Write clear API summaries and descriptions, document parameters and enums, add examples, and link to related content. url: https://www.elastic.co/elastic/docs-builder/docs/3016/contribute-docs/api-docs/guidelines applies_to: - Elastic Cloud Serverless: Generally available - Elastic Stack: Generally available --- # Add core content This page covers the core guidelines for excellent API docs. Learn how to write clear summaries and descriptions, create helpful examples, and add useful links. ## Write summaries and descriptions Most objects in your OpenAPI specification accept both concise summaries and detailed descriptions to help users understand their purpose and usage. ### Write summaries Clear, single-sentence summaries help users understand the components of your API at a glance. They appear in various contexts like IDEs, search results, and documentation overviews. Here are some principles for writing effective summaries: - **Be concise:** Keep API operation summaries short (between 5-45 characters) because they appear in different contexts where space is limited - **Start with a verb:** Use action words like "Get", "Update", "Delete", "Create" - **Use basic verbs:** Use basic verbs (Get, Update, Delete) rather than verbose alternatives (Retrieve, Return, List) - **Include articles:** "Delete a space", "Delete spaces", "Delete all spaces" - **Use sentence case:** Capitalize only the first word and proper nouns #### Summary examples

In OpenAPI specifications, summaries are defined in the `summary` field: ```yaml paths: /indices/{index}: get: summary: Get index information description: Retrieve configuration and mapping information... ```

In the Elasticsearch TypeScript definitions, summaries are added as JSDoc comments above class definitions: ```ts /** * Get index information */ class GetIndexRequest { // ... } ``` **Notes:** - Use 30 characters maximum to avoid text wrapping in generated output - Don't add a period at the end

### Write descriptions Most OpenAPI objects accept a `description` field. For best results, add descriptions wherever possible. Elastic APIs are generally complex, and summaries alone are not enough to explain their purpose and usage. Descriptions enable you to add detailed explanations of your OpenAPI objects. They are essential for transforming machine-readable information into nicely formatted, human-readable prose. You can add paragraph breaks, links, or lists to your descriptions. Here are some principles for effective descriptions: - **Explain purpose and impact:** What does this operation or parameter do and why would users need it? - **Provide context:** What are the prerequisites or related concepts users should know? - **Use formatting:** Use paragraph breaks, lists, and other formatting options to make descriptions readable - **Reference related operations:** [Link](#add-links) to complementary APIs or prerequisite steps - **Provide usage guidance:** How should users typically use this parameter or operation? - **Document constraints:** What are the valid values, formats, or limitations? - **Explain data relationships:** For list parameters, clarify how multiple values are handled (comma-separated, arrays, and so on) - **Document special formats:** Include expected formats for timestamps (ISO-8601) and patterns for wildcards - **Ensure comprehensive coverage:** Ensure all parameters, tags, and information sections include clear descriptions - **Use inclusive language:** Avoid problematic terminology and use inclusive language throughout. Refer to [Word choice](https://www.elastic.co/elastic/docs-builder/docs/3016/contribute-docs/style-guide/word-choice) #### Description examples

**Operation descriptions**Add descriptions to operation definitions: ```yaml paths: /books: get: summary: List books description: | Retrieve a paginated list of books from the library catalog. Use query parameters to filter by author, genre, or publication year. Results are sorted by title by default. ``` **Parameter descriptions**Add descriptions to parameter definitions: ```yaml parameters: - name: author in: query description: | Filter books by author name. Supports partial matching - searching for "smith" will find "John Smith" and "Jane Smithson". schema: type: string example: "Jane Austen" ``` **Schema property descriptions**Add descriptions directly to schema properties: ```yaml components: schemas: Book: type: object properties: publishedDate: type: string format: date description: | The date when the book was first published in ISO 8601 format. Used for filtering and sorting operations. ``` Learn more about providing long descriptions in YAML in the [OpenAPI docs](https://learn.openapis.org/specification/docs.html#providing-long-descriptions-in-yaml).

**Operation descriptions**Write comments above class definitions: ```ts /** * Get index information * * Retrieve configuration and mapping information for one or more indices. * You can use this API to check index settings, mappings, and other metadata * before performing operations that might affect the index structure. */ class GetIndexRequest { // ... } ``` **Parameter descriptions**Write comments inline: ```ts class SearchRequest { /** * A comma-separated list of data streams, indices, and index aliases used to limit the request. * Wildcard expressions (*) are supported. */ index: string } class AlertRule { /** * An ISO-8601 timestamp that indicates when the event was detected. */ detectedAt: string } ```

## Document parameters Proper documentation helps users understand what values are expected, how to construct valid requests, and explains the effects of changing defaults. Here are some principles for documenting parameters: - **Write clear descriptions:** Follow the general guidance for [writing descriptions](#write-descriptions) - **Indicate requirement status appropriately:** - Path parameters are always required (`required: true` must be present) - **Document parameter constraints:** Specify valid formats, patterns, or value ranges - **Explain parameter relationships:** Clarify how multiple parameters work together and any dependencies between them ### Examples: Path parameters

Define path parameters directly in the path specification: ```yaml paths: /users/{userId}/posts/{postId}: get: summary: Get a specific post parameters: - name: userId in: path required: true description: The unique identifier of the user schema: type: string example: "12345" - name: postId in: path required: true description: The unique identifier of the post schema: type: string example: "post-abc" ``` For optional variations, create separate paths: ```yaml paths: /books: get: summary: List all books /books/{category}: get: summary: List books by category parameters: - name: category in: path required: true description: The book category to filter by schema: type: string example: "fiction" ```

For endpoints that can accept optional parameters, add multiple paths in the `urls` array and define them in `path_parts`: ```ts urls: [ { path: "/{index}/_doc/{id}", methods: ["PUT", "POST"] }, { path: "/{index}/_doc", methods: ["POST"] } ] path_parts: { /** * A unique identifier for the document... */ id?: Id /** * The name of the data stream or index to target... */ index: IndexName } ```

## Document enum values Enumerated types (enums) define a fixed set of allowed values for a property. Well-documented enum values help users understand the purpose of each option and when to use it. Here are some principles for documenting enum values: - **Clarify non-obvious meanings:** Document when the purpose isn't clear from the name alone - **Provide usage guidance:** Explain when to use each option and any performance implications - **Document special behavior:** Note if some values are deprecated, experimental, or have unique characteristics - **Keep it concise:** Use brief, focused descriptions that explain the essential differences You can skip documenting enum values that are self-explanatory (like `true`/`false`) or follow standard conventions (like HTTP status codes). ### Examples

In OpenAPI specifications, enum descriptions are documented in schema definitions: ```yaml components: schemas: SearchType: type: string enum: - query_then_fetch - dfs_query_then_fetch - query_and_fetch description: | The search execution strategy: - `query_then_fetch`: Searches across all fields using default settings - `dfs_query_then_fetch`: Performs distributed frequency scoring before fetching results - `query_and_fetch`: Fetches results immediately without scoring optimization ```

In TypeScript definitions, enum descriptions are added as JSDoc comments above each value: ```ts export enum SearchType { /** Searches across all fields using default settings. */ query_then_fetch = "query_then_fetch", /** Performs distributed frequency scoring before fetching results. */ dfs_query_then_fetch = "dfs_query_then_fetch", /** Fetches results immediately without scoring optimization. */ query_and_fetch = "query_and_fetch" } ``` The compiler automatically extracts these descriptions and formats them as lists in the property documentation: - `query_then_fetch`: Searches across all fields using default settings - `dfs_query_then_fetch`: Performs distributed frequency scoring before fetching results - `query_and_fetch`: Fetches results immediately without scoring optimization

## Add examples Examples help users understand how to use your API with realistic request and response data. Well-written descriptions transform examples from code snippets into effective learning tools. Here are some principles for effective examples: - **Use realistic data:** Provide examples that reflect actual use cases rather than placeholder values - **Write clear summaries:** Introduce the example with a very brief summary (<45 characters) that explains its purpose (reused as dropdown label in the docs) - **Write clear descriptions:** Explain what the example accomplishes in more detail and why it's useful - **Include edge cases:** Show how to handle optional parameters, the error conditions, and the effects of changing defaults - **Point out key details:** Highlight important aspects users might miss - **Show variations:** Demonstrate alternative approaches or related concepts - **Provide realistic response bodies:** Each response body should have a realistic example. It must not contain any sensitive or confidential data - **Include success responses:** Include at least one example for each success response (HTTP 200) #### Generated examples In some cases examples are automatically generated as part of the publishing process. It's preferable to include curated examples in your OpenAPI document with a realistic combination of property values. You can provide more than one example object in the examples field, so consider adding examples that reflect the most common use cases. To override generated `curl` examples and optionally provide an equivalent Console or language-specific example, use the `x-codeSamples` extension described in [Custom code examples in Bump.sh](https://docs.bump.sh/help/specification-support/doc-code-samples). When you use validation tools to check your API specification, examples are helpful for ensuring that you haven't missed things like nullable data types.Learn more: - [The example object](https://spec.openapis.org/oas/latest#example-object) - [Add examples](https://swagger.io/docs/specification/adding-examples) ### Examples

The OpenAPI specification supports examples in several ways, which vary across OpenAPI versions.**Individual parameter examples** can be defined directly in specifications: ```yaml components: schemas: SearchRequest: type: object properties: department: type: string description: Filter employees by department example: "engineering" hireDate: type: string format: date description: Minimum hire date in ISO 8601 format example: "2020-01-01" ``` For more complex examples, OpenAPI provides the [Example Object](https://spec.openapis.org/oas/v3.0.3#example-object), which can be attached to request bodies, responses, or parameters.

**File-based examples** use a structured folder approach alongside your API specification: ``` /specification/your-api/examples/ ├── request/ │ ├── basic-search.yml │ └── advanced-filters.yml └── response/ ├── success.yml └── error.yml ``` Each example file follows the [OpenAPI Example object specification](https://spec.openapis.org/oas/v3.0.3#example-object) in YAML format: ```yaml summary: Search with filters method_request: GET /employees/_search description: > Combine multiple conditions using a bool query. This example finds employees in the engineering department hired after 2020. Notice how the bool query's "must" clause requires both conditions to match. value: |- { "query": { "bool": { "must": [ {"match": {"department": "engineering"}}, {"range": {"hire_date": {"gte": "2020-01-01"}}} ] } } } ``` **Required fields:** - `summary` - Brief label that appears in the docs - `value` - The actual request/response body - `method_request` - HTTP method and path (request examples only) For Elasticsearch APIs, you only need to provide Console examples. Examples for other programming languages (including cURL) are **generated automatically** and added to [docs/examples/languageExamples.json](https://github.com/elastic/elasticsearch-specification/blob/main/docs/examples/languageExamples.json).

## Add links Links help users navigate between related APIs and find additional context in narrative documentation. Strategic linking improves discoverability and helps users understand how different operations work together. Here are some principles for effective linking: - **Link to prerequisite concepts:** Connect APIs to foundational concepts users need to understand - **Reference related operations:** Point to complementary APIs that users typically need together - **Provide narrative context:** Link to guides that explain when and how to use the API effectively - **Use descriptive link text:** Choose meaningful labels that indicate what users will find - **Validate link targets:** Ensure links point to current, accurate documentation ### Examples

Use the `externalDocs` field to link to narrative guides in the main Elastic documentation: ```yaml paths: /search: post: summary: Search documents description: Execute a search query against one or more indices externalDocs: description: Try the hands-on Query DSL tutorial url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html ``` You can have only one URL within `externalDocs`. For multiple links, use inline markdown in descriptions. **Related operation links** can be referenced in descriptions using standard markdown: ```yaml paths: /indices/{index}: put: summary: Create an index description: | Creates a new index with optional settings and mappings. See also: [Delete Index](delete-index) and [Update Index Sets](update-index-settings). ```

**External documentation links** use the `@ext_doc_id` annotation to connect to narrative guides. This is transformed into an OpenAPI `externalDocs` field in the [compilation process](/elastic/docs-builder/docs/3016/contribute-docs/api-docs/overview#example-elasticsearch): ```ts /** * @variants container * @non_exhaustive * @ext_doc_id query-dsl */ export class QueryContainer { // ... } ``` **API reference links** use the `@doc_id` annotation for language client generation and Console integration: ```ts /** * @rest_spec_name indices.create * @doc_id indices-create-index */ export interface CreateIndexRequest extends RequestBase { // ... } ``` Both annotations require corresponding entries in [`specification/_doc_ids/table.csv`](https://github.com/elastic/elasticsearch-specification/blob/main/specification/_doc_ids/table.csv): Each endpoint can have only one `@ext_doc_id`. For multiple links, use inline markdown in descriptions.

## Set default values Default values can be applied to optional parameters or properties in OpenAPI specifications using the `default` field. It's important to explain how changing these defaults affects the behavior of the API in the parameter description. ### Examples

Specify defaults directly in schema definitions: ```yaml components: schemas: SearchSettings: properties: size: type: integer default: 10 timeout: type: string default: "1m" ``` For arrays: ```yaml parameters: - name: fields in: query schema: type: array items: type: string default: ["id", "name", "created"] ```

Use the `@server_default` annotation for optional properties: ```ts class Foo { /** @server_default "hello" */ baz?: string /** @server_default ["hello", "world"] */ tags?: string[] } ```

## Lint your API docs Linting your API docs helps ensure consistency, correctness, and adherence to best practices. It catches common issues like missing descriptions, inconsistent naming, and formatting errors.

Run this command to lint your OpenAPI files: ```bash make lint-docs ``` Refer to [the Elasticsearch quickstart](https://www.elastic.co/elastic/docs-builder/docs/3016/contribute-docs/api-docs/elasticsearch-api-docs-quickstart) to learn more about the linting workflow.

Run this command from the `oas_docs` directory to lint your OpenAPI files: ```bash 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`.Refer to [the Kibana quickstart](https://www.elastic.co/elastic/docs-builder/docs/3016/contribute-docs/api-docs/kibana-api-docs-quickstart) to learn more about the workflow.